XUI Installation Guide

XUI is built around the J2EE architecture utilizing the power and extensibility of XML and Java. XUI works with a typical servlet container such as Jakarta-Tomcat. XUI is platform independent, so anywhere that the Tomcat container can be deployed, it is possible to setup the XUI environment. The examples below focus on setting up the environment in a Microsoft Windows environment with side notes for other Operating Systems.

XUI's current release supports the following versions of Jakarta-Tomcat:

  • Tomcat 4.0.6
  • Tomcat 4.1.31
  • Tomcat 5.0.28

To get started, you will need to have the J2EE Server or J2SE SDK and Jakarta-Tomcat installed. J2EE and J2SE SDK is available from java.sun.com. Jakarta Tomcat is available from jakarta.apache.org. Follow the steps below in setting up the J2EE and Jakarta-Tomcat Environment.

  1. Setting up the J2EE Environment
  2. Setting up the Jakarta-Tomcat Environment

Installing XUI

XUI distribution comes in two file types: a WAR file and a ZIP file. If you you would like to start with a fresh application, then the war file is the way to go. If you already have an existing application and you would like to integrate XUI into it, then the ZIP file is the better option. Download XUI.

Installing using an XUI WAR File

XUI comes as a WAR file and can be "exploded" in your $TOMCAT_HOME/webapps folder. Whatever the WAR file name is, this will become the name of the application directory once unzipped and run as an application. In our case, when the WAR file is exploded, it will create an application named "xui-framework" under $TOMCAT_HOME/webapps.

To install XUI by using the WAR file, follow these steps:

  1. Stop Tomcat if it's already running.
  2. Copy the XUI WAR file into $TOMCAT_HOME/webapps.
  3. Start Tomcat (This will automatically unzip the WAR file).
  4. Verify under $TOMCAT_HOME/webapps that there is a new folder named "xui-framework". You can rename this folder however you want, but for our examples, we will be using "xui-framework" as the name of the application.
  5. Delete or copy the WAR file into another directory. If you get the an error saying the file cannot be deleted, try to stop Tomcat first before deleting.
  6. In this new application folder, look for a file named "web.txt" under the WEB-INF folder. Rename this file to "web.xml".
  7. Before you can test the application, the XUI license must be installed. Go to License Installation section to install the XUI License.

Installing using an XUI ZIP File

XUI is also distributed as a ZIP file where you can extract portions of the file into an existing application. This can also be used to create a new application if desired.

To install XUI from the ZIP file distribution, follow these steps:

  1. Stop Tomcat if it's already running.
  2. Unzip or extract all the contents of the XUI .zip file directly into your $TOMCAT_HOME/webapps folder.
  3. This will produce a folder named xui-framework containing all necessary files and resources to run an XUI application.
  4. By default, this will extract as "xui-framework". You can rename this folder however you want, but for our examples, we will be using "xui-framework" as the name of the application.
  5. In this new folder, look for a file named "web.txt" under the WEB-INF folder. Rename this file to "web.xml".
  6. Before you can test the application, the XUI license must be installed. Go to License Installation section to install the XUI License.

Installing XUI into an existing application

XUI can be installed into an existing application by using the same ZIP file as used above. To install XUI into an existing application, follow these steps:

  1. Unzip or extract all the content of the ZIP file into a convenient location.
  2. This will produce a folder named xui-framework containing all the necessary files and resources to run an XUI application.

From this new folder, a few files and folders are need to be copied to your existing application where you would like to run XUI:

  1. XUI-INF Folder - Contains all the necessary support files such as CSS, JavaScript, Icons. This also contains all the PLAFs (Pluggable Look-and-Feel), scripts. This folder needs to be copied into $TOMCAT_HOME/webapps/$APP_NAME/.
  2. web.txt (web.xml) - Look for a file named "web.txt" under the WEB-INF folder. Copy the contents of this file into your existing web.xml file. If you don't have an existing web.xml file, rename "web.txt" to "web.xml" and copy it into $TOMCAT_HOME/webapps/$APP_NAME/WEB-INF directory. Make sure that you always stop and restart Tomcat when replacing or editing this file.
  3. The following JAR files need to be copied to $TOMCAT_HOME/webapps/$APP_NAME/WEB-INF/lib/ directory:
  4. xui-framework.jar File - The main XUI JAR file containing the XUI Framework Application.
  5. xercesImpl.jar and xsltc.jar- XUI essential JAR files for XML/XSL parsing
  6. jsf-api.jar and jsf-impl.jar - OPTIONAL. Necessary if you will be using JSF (Java Server Faces) features with XUI. For example, if you will be using data-binding through JSF, then these jar files are necessary.
  7. standard.jar and jstl.jar - OPTION. Necessary JAR files if you will be using JSF with JSTL (Java Standard Tag Libraries).

Installing the License

XUI License is provided as an encrypted text file named "xui.license". Whether you have aquired this license via email or have downloaded it from the website, this file needs to be loaded into your application. If you do not have a license file, contact us to acquire a copy.

To install the license, go to the XUI License Installation section.

Installation Notes:

XUI is using newer version of xalan and xsltc, and this can only be done by overwriting the JDK endorsed libraries. This can be accomplish in several ways depending on the Tomcat version.

For Tomcat 4.1.31 and 5.0.28 users, follow these steps:

Tomcat 4.1.31 and 5.0.28 have the concept of the endorsed libraries.

  1. Copy the files to [tomcat_home]/common/endorsed
  2. Tomcat should automatically add the endorsed libraries.

For Tomcat Tomcat 4.0.6 users, follow these steps:

  1. Copy the files (xalan.jar and xsltc.jar) to a certain directory that will be the [library_path]
  2. Create a batch file which will add the endorsed libraries
java -jar -Dorg.xml.sax.driver=org.apache.crimson.parser.XMLReaderImpl 
-Djav a.endorsed.dirs="[library_path]" "[tomcat_home]/bin/bootstrap.jar" start

or as an alternative, add the java.endorsed.dirs to the startup command for tomcat

  • Create a java endorsed dir environment variable
    JAVA_ENDORSED_DIRS=[library_path]
  • Find the java command which runs the server and make sure you have endorsed dir declared.
For Windows 
java -Dorg.xml.sax.driver=org.apache.crimson.parser.XMLReaderImpl -Djava.en 
        dorsed.dirs="%JAVA_ENDORSED_DIRS%"
For Linux 
java -Dorg.xml.sax.driver=org.apache.crimson.parser.XMLReaderImpl -Djava.en 
        dorsed.dirs="$JAVA_ENDORSED_DIRS"
For more information on Xalan and JDK1.4 issues go to http://xml.apache.org/xalan-j/faq.html#faq-N100CC

For Tomcat 4.1.31 and 5.0.28 with JDK 1.5 users, follow these steps:

Tomcat 4.1.31 and 5.0.28 have the concept of the endorsed libraries. These instructions are based on preliminary test results. More detailed testing is underway with the end view of certifying XUI on JDK 1.5 under various Tomcat versions.

  1. Download the libraries from Download page and copy the files to [tomcat_home]/common/endorsed/
  2. Tomcat should automatically add the endorsed libraries. Please see Figure 1. Note the "Date Modified" for each of the files.
  3. Please note initial tests from fresh Tomcat installation have been successful. More tests need to be conducted for existing Tomcat installations to determine possible conflicts/exceptions.

Figure 1. Endorsed Libraries

Back to: Application Guide
 

 

COPYRIGHT © 1997–2006 JWAY GROUP, Inc.
All Rights Reserved. XUI is a registered trademark of JWAY GROUP, Inc.
All other designated trademarks and brands are properties of their respective owners.