Contents
Previous
Next
| UIX Developer's Guide |
Contents |
Previous |
Next |
In Part I of the UIX Developer's Guide, you have learned the basics of developing UIX-based applications. However, there is one last basic topic which you'll need to know or you won't get very far: how to install/deploy your application! Installing a UIX-based application is not much different from installing any other web application. This chapter demonstrates the steps involved in the installation process by walking through the installation of a simple "Hello, World!" UIX application. Although your application is certainly more complex than this trivial sample application, the necessary installation steps are largely the same.
This chapter contains the following sections:
Before we get started with the installation process, you'll need to be familiar with the class libraries, technologies and resources used by UIX. UIX itself consists of one class library, uix2.jar, as well as a set of installable resources, such as images, style sheets, and JavaScript libraries, which are distributed via the uix2-install.zip file.
The following sections describe all of the dependencies required by UIX. All of the class libraries described in this section are distributed with both Oracle's application server product, Oarcle9iAS, as well as Oracle's development tool suite, Oracle9iDS. However, you may need to obtain some some of the core technologies such as the Java JDK from other sources.
UIX is a Java-based technology, and as such requires the Java Runtime Environment. In particular, UIX requires at least the 1.2 version (preferably 1.3.1, or 1.4 once it is available in a production release) of the Standard Edition of the Java 2 platform.
The Java 2 Runtime Environment for the Windows, Solaris and
Linux platforms can be downloaded from Sun Microsystems (http://java.sun.com/j2se/).
Most other platform vendors distribute a JRE with
their operating systems, although you may want to visit
your platform vendor's web site to see whether you have the
latest available version. In general, more recent versions
of Java perform better than older versions, so it may be
worthwhile to investigate your JRE options. (Note: You can
use the java -version command to
determine what version of the JRE you are running.)
UIX requires a servlet engine which supports version 2.0 or later of the Servlet API. Since most servlet engines meet this requirement, UIX-based applications should be able to run on just about any servlet engine. Oracle's application server, Oracle 9iAS, currently supports two servlet engines:
UIX has also been tested with recent versions of the Apache Tomcat servlet engine.
The Servlet API itself is defined by Sun Microsystems. More information on the Servlet API can be found at Sun's Java Servlet Technology site (http://java.sun.com/products/servlet/).
UIX requires an XML parser to parse a variety of XML document types, including uiXML documents, XML Style Sheet language (XSS) documents, and UIX Dynamic Images metadata documents. UIX clients are encouraged to use the Oracle XML Parser For Java, version 9. The Oracle XML Parser JAR file, xmlparserv2.jar, is shipped with both Oracle's application server (Oracle 9iAS) and development tools (Oracle 9iDS). More information about the Oracle XML Parser, along with the latest beta and production versions, can also be found at the Oracle Technology Network (http://otn.oracle.com/tech/xml/xdk_java/content.html).
Although the Oracle XML Parser is the preferred parser for UIX,
UIX's XMLProvider API allows you to plug
in almost any XML parser. UIX includes
XMLProvider bindings for
both the Oracle XML Parser and the Apache Xerces parser. You
are welcome to develop an XMLProvider
binding for your favorite XML parser.
Note, UIX also requires the SAX 2 API for XML parsing. The SAX 2 API is the industry standard interface for event-based XML parsing. Most XML Parsers already support the SAX 2 API. XML parsers which support the SAX 1 API but not the SAX 2 API can be adapted to the SAX 2 API using the SAX 2 adapter classes provided by Meggison Technologies (http://www.megginson.com/SAX/).
UIX uses the Apache Regexp package for regular expression parsing. The Apache Regexp JAR file, regexp.jar, is shipped with both Oracle9iAS and Oracle9iDS. Documentation and the latest versions of this package are also available from the Apache Regexp site (http://jakarta.apache.org/regexp/index.html).
The Share package provides a set of utility classes which used by a variety of Oracle products and technologies. The Share jar file, share.jar, is distributed with Oracle 9iAS and 9iDS.
The UIX Dynamic Images technology allows some of the images used by UIX pages (such as buttons and tab bars) to be created at runtime as needed. In order to create these images, UIX Dynamic Images makes use of the AWT graphics library. Prior to Java 2 version 1.4, AWT implements much of its functionality via platform-specific native graphics capabilities. In Unix environments, the underlying graphics layer is implemented via the X Window System. The X Window System is a network-based graphics system, in which graphics requests are sent (possibly over a network) to an X Server which processes the request by performing requested graphics operation.
When deploying UIX-based applications on Unix platforms, an extra configuration step must be performed. UIX/AWT must be able to access an X Server in order for image generation to succeed. This requires that the DISPLAY environment be set to indicate the location of the X server, prior to starting the servlet engine. Setting the DISPLAY environment variable is usually a straightforward process. However, the X Window System supports a variety of security mechanisms (it is a networked system after all) which can cause problems for UIX deployments.
In the worst case, if UIX can not access the X Server, the application should run, but with image generation disabled. In this case, UIX should render alternate HTML content (for example, text links instead of button images), resulting in a slightly degraded appearance. If you see this behavior, or if you see any error messages relating to X Window System or image generation problems, see the X Server Configuration for Image Generator chapter.
Fortunately, the X server dependency and the configuration work that it requires will soon disappear. As of Java 2 version 1.4, currently in Beta, Java supports "headless" operation, in which graphics operations can be performed without the presence of an X server. In the meantime, a number of other solutions are available to alleviate some of the problems involved in X server configuration. For example, the Image Servlet can be used to offload image generation to another machine which is better suited for graphics operations. Using a the Image Servlet, image generation can be moved from a Unix middle-tier machine to a dedicated Windows image generation server, removing the need for an X server. This solution and others are discussed in detail in the X Server Configuration for Image Generation chapter.
UIX Dynamic Images imposes one other special requirement needed for image generation. In order to generate images with text based content, such as buttons or tabs with text labels, AWT must have access to fonts for any languages supported by the UIX application. Since it is highly likely that not all middle-tier environments are configured with the appropriate internationalized fonts, Oracle9iAS includes a set of True Type fonts which can be used for most languages. These fonts use the Albany type face, which is a sans-serif style, similar to Arial or Helvetica.
Oracle 9iAS includes four flavors of the Albany font. Each font is an (almost) full range Unicode font, which means that each font has glyphs for most languages. The four fonts simply differ in which glyphs are used in the Unified CJK portion of the font. The fonts are:
To make these fonts available to AWT, they must be copied (or linked) into the jre/lib/fonts directory of the Java installation. AWT will automatically locate and load any TrueType fonts that it finds in this directory. So, before installing your web application, check to see whether these four font files are present in the jre/lib/fonts directory on your machine. If not, copy the font files into this directory, or create symbolic links to these files from this directory, so that the fonts can be used during image generation.
If these fonts are not found, UIX Dynamic Images will instead use the "Dialog" AWT virtual font, which is mapped to platform-specific fonts by AWT's font.properties mechanism.
If you have specific fonts that you would like to use for image generation, you can configure UIX Dynamic Images to use your fonts by overriding the "DefaultServerFontFamily" style defined by blaf.xss. For more information on how to make such changes, see the Customization chapter.
In this section, we'll walk through the steps involved in deploying a UIX-based application in the Oracle Containers For J2EE (OC4J) servlet engine. For the purposes of this chapter, we'll use the following simple UIX document, HelloWorld.uix, as our entire application:
<?xml version="1.0" encoding="UTF-8"?>
<page xmlns="http://xmlns.oracle.com/uix/controller"
xmlns:ui="http://xmlns.oracle.com/uix/ui"
xmlns:ctrl="http://xmlns.oracle.com/uix/controller">
<content>
<pageLayout xmlns="http://xmlns.oracle.com/uix/ui">
<contents>
<header text="Hello, World!"/>
</contents>
</pageLayout>
</content>
</page>
By the end of this section, we'll be able to view this document running in the OC4J servlet engine.
In this section, we show how to deploy the sample UIX application using an "exploded" or "expanded" directory structure, in which the individual application files are accessible directly on the file system. This deployment configuration is particularly convenient during the development process, as UIX files can be easily modified and tested without requiring any repackaging. In the next section, we will look at how to deploy the same "Hello, World!" application packaged using the EAR file format, which is more suitable for deployment to production systems.
The instructions provided in this section describe the simplest of possible OC4J configurations. As such, these instructions are mostly intended for developers who simply need to run UIX documents during development. Real world application deployments will very likely take advantage of more advanced OC4J capabilities, such as load balancing and EJB hosting. These advanced topics are outside of the scope of this document, but are covered in detail in the OC4J documentation set. More information on OC4J can be found on the Oracle Technology Network (http://otn.oracle.com/tech/java/oc4j/content.html).
OC4J is a standard component of the Oracle9iAS application server. If you have already installed a recent version of Oracle9iAS, OC4J should be located in the j2ee/home directory under your Oracle Home. If you have not yet installed Oracle9iAS, you can download OC4J separately from the Oracle Technology Network (http://otn.oracle.com/tech/java/oc4j/content.html). After downloading the OC4J zip file (oc4j.zip), install OC4J by performing the following steps:
You can unzip OC4J into any directory. This should create a directory structure under the j2ee/home directory (eg. j2ee/home/applications, j2ee/home/config, etc...). Some versions of the oc4j.zip file actually contain just two other zip files - petstore.zip and a second oc4j.zip. If your zip file contains just these two files, unzip the second oc4j.zip file to produce the OC4J directory structure and files.
This command must be run from a console window (eg. DOS Shell or Unix terminal). Inside the console, change the current directory to the j2ee/home directory created in the step 1 above and run the following command:
java -jar oc4j.jar -installEnter a password for the admin user when prompted. You will need this password later for administrative tasks. (Note: In older versions of OC4J, the oc4j.jar file was named orion.jar. If you have an orion.jar file, you should substitute that for the oc4j.jar file where applicable.)
From the j2ee/home directory, run the following command to start OC4J:
java -jar oc4j.jarTo verify that the OC4J installation is working correctly, point your browser at http://localhost:8888/. Depending on your browser's proxy configuration settings, you might need to specify the complete domain name of the machine which is hosting OC4J (for example, http://localhost.your.domain.com:8888). If the installation was successful, you should see a welcome message in your browser, such as "Oracle9iAS Containers for J2EE 1.0.2.2 - Up and running".
To shut down OC4J, run the following command from the j2ee/home directory:
java -jar admin.jar ormi://localhost/ admin <your admin passord> -shutdown Each OC4J instance can host multiple J2EE applications. A J2EE application consists of any number of web components (servlets/JSPs), as well as any number of EJB components. In order to deploy any web application, including a UIX-based web application, three steps must be performed: First, the J2EE application is created. Next, the web application is created. Finally, the web application is bound to a particular URL on the OC4J server, so that it can be accessed via a web browser.
This section describes how to perform the first step by manually modifying OC4J's configuration files. All of the installation tasks described in this chapter can be performed using administrative tools such as Oracle Enterprise Manager, or by deploying directly from Oracle JDeveloper. Users are encouraged to use such tools to facilitate the deployment of UIX applications.
Create the application directory j2ee/home/applications/HelloWorldApp.
The server.xml file in the j2ee/home/config directory contains a
single <application> element for each J2EE application. The
following XML element shows how to specify this element for our sample
UIX application:
<application name="HelloWorldApp"
path="{your path}/j2ee/home/applications/HelloWorldApp"
auto-start="true"/>Add this element to the server.xml file as a child of the <application-server> element, immediately following the <global-application> element. Be sure to substitute the full path to your OC4J installation.
In this step, we create a new web application and define the web application components (in our case, the UIXServlet) which make up the web application. This work can be performed by following these steps:
After creating these directories, your directory structure should include the following directory: j2ee/home/applications/HelloWorldApp/HelloWorldWebApp.
web.xml file
Copy the entire web.xml file defined below
into the WEB-INF directory:
<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
<web-app>
<servlet>
<servlet-name>uix</servlet-name>
<servlet-class>oracle.cabo.servlet.UIXServlet</servlet-class>
<init-param>
<param-name>oracle.cabo.servlet.pageBroker</param-name>
<param-value>oracle.cabo.servlet.xml.UIXPageBroker</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>uix</servlet-name>
<url-pattern>/uix/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>uix</servlet-name>
<url-pattern>*.uix</url-pattern>
</servlet-mapping>
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
</web-app>
Be sure that there is no white space
before the XML prologue
(<?xml version="1.0"?>), as some
parsers fail to parse documents which contain white space before this
declaration.
This directory contains the application.xml configuration file, which defines metadata for the J2EE application, such as the names of any web applications that are used by the J2EE application. Create the META-INF directory under the j2ee/home/applications/HelloWorldApp directory.
The contents of the application.xml configuration file should be as follows:
<?xml version="1.0"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" "http://java.sun.com/dtd/application_1_3.dtd">
<application>
<display-name>HelloWorldApp</display-name>
<module>
<web>
<web-uri>HelloWorldWebApp</web-uri>
<context-root>/</context-root>
</web>
</module>
</application>
These contents should be saved in a new application.xml file in the following location: j2ee/home/applications/HelloWorldApp/META-INF/application.xml.
Again, be sure that there is no white space at the beginning of the file before the XML prologue.
In order to provide access to our web application via OC4J, we must
bind the web application to an URL. This binding can be set up
by adding the following element as a child of the <web-site> root element in the j2ee/home/config/default-web-site.xml file:
<web-app application="HelloWorldApp"
name="HelloWorldWebApp"
root="/greetings"/>Our sample UIX application consists of a single UIX document. Copy the content of this document from above into a HelloWorld.uix file in the j2ee/home/applications/HelloWorldApp/HelloWorldWebApp/ directory. Be sure that the HelloWorld.uix file does not contain any white space characters before the XML prologue.
Your application most likely consists of a wide variety of resources, including:
Since the web application root directory
(j2ee/home/applications/HelloWorldApp/HelloWorldWebApp in our
example) acts as the document root for the web application, most
of your application files should be copied to the appropriate
subdirectory under this directory.
In addition to having more application resource files, the other
important difference between your application and our sample
application is that your application will actually have some Java code
(for event handlers, data providers, etc...).
Copy any JAR files used by your application into the
<web app>/WEB-INF/lib directory, and any loose classes
into the <web app>/WEB-INF/classes. Alternatively, these
classes can be added to the class path as described in the
Setting the Class Path section
below.
UIX itself makes use of its own images, JSPs, Javascript libraries, and style sheets. These files are distributed in the uix2-install.zip file. Unzip the UIX installable files into the root directory of the web application. This should create the following directories:
j2ee/home/applications/HelloWorldApp/HelloWorldWebApp/cabo/images
j2ee/home/applications/HelloWorldApp/HelloWorldWebApp/cabo/jsps
j2ee/home/applications/HelloWorldApp/HelloWorldWebApp/cabo/jsLibs
j2ee/home/applications/HelloWorldApp/HelloWorldWebApp/cabo/styles
Although installing the the UIX resources in the web application root directory is by far the easiest configuration to set up, there are some drawbacks to this approach. In particular, each web application must own its own copy of these files, which can be wasteful for OC4J deployments with many web applications. A better solution is to share a common set of UIX resources which is deployed in a separate web application, or even on a separate web server. This problem and possible solutions are discussed in more detail in the Sharing UIX Installable Resources section.
The UIX classes are distributed in a single JAR file, uix2.jar, which must be added to the class path. UIX also depends on the following libraries:
Each of these JARs must be added to the class path. One way to do
this is to copy all of these files into the WEB-INF/lib directory
of the web application. Libraries that are installed in this
directory are treated as private to the web application. That is,
the classes in these libraries are loaded by an application-specific
class loader, and are not shared with other applications running
in the same servlet engine.
In some cases, it may be preferable to share a single copy of the
libraries across multiple applications. To make these
libraries available to all applications in the OC4J instance, add
a <library> element for each
JAR file into the j2ee/home/config/server.xml configuration file.
The <library> elements should
be added as children of the
<application-server> root element.
Each library element defines a single attribute,
path, which specifies the file system
path of the JAR file.
Add the following lines to the server.xml configuration file,
after substituting the appropriate parent directory for the
JAR files:
<library path="{your path}/uix2.jar"/>
<library path="{your path}/xmlparserv2.jar"/>
<library path="{your path}/regexp.jar"/>
<library path="{your path}/share.jar"/>
At this point, we should be ready to go. Shut down
and restart OC4J. You should be able to access the HelloWorld.uix page via
either of the following URLs:
http://localhost:8888/greetings/HelloWorld.uixhttp://localhost:8888/greetings/uix/HelloWorld
You may be required to provide the full domain name of your machine
(eg. http://localhost.your.domain.com:8888/greetings/HelloWorld.uix)
depending on your browser settings.
If for some reason the "Hello, World!" message is not displayed
in your browser, check the console window for error messages.
Errors should also be logged in the application-specific
error log in j2ee/home/application-deployments/HelloWorldApp/application.log,
or possibly in one of the log files under j2ee/home/log.
Although deploying your UIX application as an expanded web application may be convenient for development purposes, the expanded file format is not ideal for production deployments. Maintaining all of those files on all middle-tier servers can be cumbersome. A much more convenient way to distribute and deploy your application is as an EAR file. An EAR file is a single archive which contains your entire enterprise application, including both your web application and any supporting EJB classes. Since the EAR file format is defined by the J2EE platform specification, your EAR file should run on any J2EE-compatible container, including OC4J.
This section describes how to create and deploy an EAR file for our simple "Hello, World!" application.
Although there are many different ways to prepare and create an EAR file, and many different tools to help with this process, let's keep it simple and perform this work by hand. The EAR file format actually looks a lot like the directory structure that we created above for our expanded application deployment. We'll need to build up the following directory structure before we can create our EAR file:
---- META-INF
| ---- application.xml
|
`---- HelloWorldWebApp
|---- HelloWorld.uix
|---- cabo/
| |---- images
| |---- jsLibs
| |---- jsps
| |---- styles
`---- WEB-INF/
|---- web.xml
`---- lib
|---- uix2.jar
|---- xmlparserv2.jar
|---- regexp.jar
`---- share.jar
By now, you should be familiar with all of the files that are needed to assemble this directory structure. Follow these steps to install the necessary files:
Copy the contents from the sample file from
above into an application.xml
file in the META-INF directory. As always, make sure that the
file starts with the XML prologue
(<?xml version="1.0"?>). For this and
all other XML files, be sure that there is no white space before the
prologue.
web.xml file
Again, we can just reuse the sample web.xml file that we
used from our expanded deployment. Copy the contents from
the sample web.xml file above into
a web.xml file in the HelloWorldWebApp/WEB-INF directory.
Copy the sample HelloWorld.uix contents above into a HelloWorld.uix file in the HelloWorldWebApp directory.
Unzip the files in the uix2-install.zip file into the HelloWorldWebApp directory.
Create a lib directory under WEB-INF and copy in all of the required JAR files:
By including our own private copy of the UIX installable resource files
and all dependent JAR files, our EAR file will be a self-contained
application which can be deployed on an J2EE application server.
However, using private copies of the UIX resources and all necessary
JAR files is not ideal for all deployments. For example, when
deploying to an OC4J instance which is hosting many web applications,
it would be more efficient to install the JAR files in some common location
where they can be shared by all of the applications. In this case,
you will need to add <library>
elements to the server.xml file for each JAR file, as shown
in the Setting the Class Path
section above.
Similarly, it might be more efficient for multiple web applications to share common versions of the UIX resource files (images, style sheets, etc...). See the Sharing UIX Installable Resources section for more information on how to set up such as configuration.
The EAR file format uses the JAR file format to archive all of the application directories and files. So, an EAR file is basically a JAR file with a particular directory structure and metadata files. We have already created the necessary directory structure and copied all of the configuration files into place. The next step is to create the archive file.
Although there are many tools that can be used to create EAR files,
perhaps the simplest to use is the jar
command that ships with the JDK. To create the EAR file for our
sample application, launch a console/terminal window and change the
current directory to the top level of the directory structure that
we just created. (There should be two child directories - META-INF
and HelloWorldWebApp.) Then, execute the following command:
jar -cvf ../helloworld.ear .This first argument, "-cvf", indicates that a new EAR file should be created with verbose output. The second argument is the name of the EAR file. In this case, we specify that the EAR file should be created in the parent directory, so that we don't end up trying to add the EAR file to itself! The final argument, ".", indicates that all of the contents of the current directory should be archived.
Now that we've got an EAR file, we need to let OC4J know about
it. To do this, add the following element to the j2ee/home/config/server.xml
configuration file as a child of the
<application-server> element:
<application name="HelloWorldApp"
path="{your path}/helloworld.ear"
auto-start="true"/>Be sure to substitute the appropriate path to the helloworld.ear file for your file system.
As we learned earlier when deploying the expanded version of our
web application in OC4J, each web application must be bound to
an URL in order for it to be accessible via a web browser. To
specify this binding, simply add the following element to the
j2ee/home/config/default-web-site.xml configuration file, as
a child of the <web-site>
element:
<web-app application="HelloWorldApp"
name="HelloWorldWebApp"
root="/greetings"/>Now we are ready to test our EAR file deployment. This step is actually the same whether you are deploying with an EAR file or an expanded file structure, so follow the same steps that we used above.
Tomcat is a pure Java servlet engine developed by the Jakarta Project of the Apache Software Foundation. The latest version of Tomcat, Tomcat 4.0, supports the 2.3 version of the Servlet API. This section walks through the steps that are needed to deploy the "Hello, World!" sample application in the Tomcat servlet engine.
Tomcat binaries are available for download from the Apache Jakarta web site
(http://jakarta.apache.org/tomcat/index.html). Installing Tomcat
is easy - just unzip the jakarta-tomcat ZIP file. This should create
a directory structure under the jakarta-tomcat directory. To test
the installation, start up Tomcat by running the startup.bat (Windows)
or startup.sh (Unix) script in the jakarta-tomcat/bin directory.
Tomcat uses 8080 as its default port. After Tomcat starts up, you
should be able to view a welcome page at http://localhost:8080. (You
may need to specify the full domain name for your machine, depending
on your browser's proxy settings.)
Like OC4J, Tomcat 4.0 is a Servlets 2.3-compatible servlet engine. Since recent versions of the Servlet API define specific directory structure and configuration file formats for all web applications, much of the installation process should be familiar to you by now. The following steps show how to deploy a UIX-based web application in an expanded file configuration.
In Tomcat, the name of the web application directory is also used as the
"web-path root" used to access the application. We'll use the
name "greetings", so that we can access our HelloWorld.uix
document at the URL /greetings/HelloWorld.uix.
Create a greetings and greetings/WEB-INF directory under the
jakarta-tomcat/webapps directory.
web.xml file
Since the Servlets 2.2 specification defines the web.xml file
format, we can just reuse the same web.xml
that we used for our OC4J deployment. Copy the contents of this
document into a web.xml file in the
jakarta-tomcat/webapps/greetings/WEB-INF directory.
Don't forget to remove any white space before the XML prologue!
Copy the contents of our HelloWorld UIX document from
above into a HelloWorld.uix
file in the greetings directory. This directory
serves as the document root for the web application.
Unzip the files in the uix2-install.zip file into the greetings directory.
Copy uix2.jar, xmlparserv2.jar, share.jar and regexp.jar into
the greetings/WEB-INF/lib directory. Alternatively,
if you want to run multiple UIX-based web applications on a
single Tomcat instance, place the JAR files in the
jakarta-tomcat/lib directory. Tomcat automatically adds any
JARs from this directory onto the class path.
Start Tomcat by running the jakarta-tomcat/bin/startup.bat or
startup.sh script. You should be able to view our hello message
at either of the following URLs:
http://localhost:8080/greetings/HelloWorld.uixhttp://localhost:8080/greetings/uix/HelloWorld
If you don't see the page as expected, check the console window for any
error messages logged by Tomcat. Tomcat also logs error messages to the
log files under jakarta-tomcat/logs.
Apache JServ is a legacy servlet engine which has not been updated to support recent versions of the Servlet API. JServ only supports the 2.0 version of the Servlet API. To put this in perspective, the 2.1 version of the Servlet API was originally published in 1998, and the current version of the Servlet API, 2.3, is already supported by most servlet engines. However, Oracle 9iAS still supports JServ, and as such UIX has maintained compatibility with the 2.0 version of the Servlet API.
This section describes how to install a UIX application into the default servlet zone of a JServ instance. It assumes that you already have a functional version of JServ installed, presumably in conjunction with a recent release of Oracle 9iAS. Instructions for how to install JServ are beyond the scope of this document. If you haven't already installed JServ, we recommend that you consider using a more current servlet engine, such as OC4J.
Since JServ predates the web application specifications that evolved during the Servlet 2.2 timeframe, deploying to JServ is quite different than deploying the more recent servlet engines such as OC4J and Tomcat. Rather than creating and configuring a web application, JServ simply requires that you specify an alias for your servlet class. The following steps walk through this process of setting up our sample application in JServ.
Servlet aliases are defined on per-servlet zone basis, in the servlet zone-specific properties file. For the purposes of this example, we'll install the BajaServlet into the default servlet zone and define a "uix" alias. This allows the BajaServlet to be invoked with the URL "/servlets/uix". Add the following line to the zone.properties in the Apache/Jserv/etc directory.
servlet.uix.code=oracle.cabo.servlet.BajaServletAdd the following line to the zone.properties file in the Apache/Jserv/etc directory:
servlet.uix.initArgs=oracle.cabo.servlet.pageBroker=oracle.cabo.servlet.xml.UIXPageBroker
This statement specifies that we want to use the
UIXPageBroker for our page broker.
Copy the HelloWorld UIX content from above into a HelloWorld.uix file in the document root (typically "htdocs") of your web server.
Unzip the uix2-install.zip file into the document root of your web server.
You'll need to add a "wrapper.classpath" entry to the Apache/Jserv/etc/jserv.properties configuration file for the UIX Jar file and all of its dependencies. Add the following lines, after substituting the actual path for your file system:
wrapper.classpath={your path}/uix2.jar
wrapper.classpath={your path}/share.jar
wrapper.classpath={your path}/xmlparserv2.jar
wrapper.classpath={your path}/regexp.jar
After completing these steps, you should be able to view our
HelloWorld.uix document by starting the Apache web server
(using the apachectl start command,
assuming that your JServ instance is configured to start
automatically), and goinig to the following URL:
http://localhost:7778/servlets/uix/HelloWorldYou may need to adjust the port number for your installation. To determine the actual port used by your Apache instance, look for the "Port" entry in the httpd.conf file.
Check the Jserv/logs/jserv.log, Apache/logs/access_log and Apache/logs/error_log files for error messages if problems occur.
UIX exposes a variety of initialization parameters which can be used to configure various facets of the UIX application, such as which XML parser should be used, or where to find UIX files on the file system.
In servlet engines which support the Servlet 2.2 API or greater, such
as OC4J and Tomcat, initialization parameters can be specified in
uix-config.xml, as servlet initialization parameters, or
as context initialization parameters. For information on how to set
up a uix-config.xml file, see the Configuration chapter. Servlet
initialization parameters are specific to a particular servlet
instance. These parameters are specified in the application's
web.xml file using the <init-param>
element. For example, the following sample shows how to use the
oracle.cabo.image.headless initialization parameter to
disable dynamic image generation:
<web-app>
<servlet>
<!-- Define the servlet and PageBroker here... -->
<!-- A servlet initialization parameter -->
<init-param>
<param-name>oracle.cabo.image.headless</param-name>
<param-value>true</param-value>
</init-param>
</servlet>
</web-app>
Note that the <init-param> element
is contained within the <servlet>
element. The value of this servlet initialization parameter is
specific to this particular servlet instance.
This can also be specified in uix-config.xml:
<?xml version="1.0" encoding="ISO-8859-1"?>
<configurations xmlns="http://xmlns.oracle.com/uix/config">
<default-configuration>
<headless>true</headless>
</default-configuration>
</configurations>
Unlike servlet initialization parameters, context initialization parameters
are specified once for the entire web application, independent of any
particular servlet instance. These parameters are specified using the
<context-param> element:
<web-app>
<!-- A context initialization parameter -->
<context-param>
<param-name>oracle.cabo.image.headless</param-name>
<param-value>true</param-value>
</context-param>
</web-app>
Note that the <context-param> element is a child of
the <web-app> element. The value of the context
initialization parameter is global to the web application.
One advantage of context initialization parameters over servlet
initialization parameters is that OC4J allows the values of context
initialization parameters to be overridden at deployment time. New
deployment-specific values for context initialization parameters can
be specified in the web application's orion-web.xml file
using the <context-param-mapping> element. For
example, the following orion-web.xml file overrides the
oracle.cabo.image.headless value that we specified in our
web.xml file above:
<?xml version="1.0"?>
<!DOCTYPE orion-web-app PUBLIC "-//Evermind//DTD Orion Web Application 2.3//EN" "http://xmlns.oracle.com/ias/dtds/orion-web.dtd">
<orion-web-app>
<!-- Set a deployment-specific value for the headless parameter -->
<context-param-mapping name="oracle.cabo.image.headless">false</context-param-mapping>
</orion-web-app>
Without the <context-param-mapping>
mechanism, deployers would be required to modify initialization
parameter values directly in their uix-config.xml or web.xml files. This task is actually
more difficult than it sounds, since these files may be buried
inside of a WAR file which is bundled into an EAR file. Setting new
parameter values in the orion-web.xml file provides a much quicker and
cleaner solution.
There is one caveat that developers must be aware of when deciding
which initialization parameters to set by default. OC4J only allows
context initialization parameters that are specified in the web.xml
file to be overridden in the orion-web.xml file. So, when creating
your web.xml file, be sure to add default (or empty) values for any
context initialization parameters that you would like to allow your
customers to set.
Older servlet engines, such as Apache JServ, define their own mechanisms for specifying initialization parameters. In JServ, initializations parameters are specified in the jserv.properties via the servlet.<alias>.initArgs syntax.
All of the UIX
servlet initialization parameters are optional except for one.
The oracle.cabo.servlet.pageBroker
parameter must be specified if the UIX Controller is used.
The following table lists each servlet initialization parameter supported by UIX, including the name of the class which defines the parameter. A particular parameter is only applicable if your application uses the defining class or one of its subclasses.
| Name | Defining Class | Value |
|---|---|---|
| oracle.cabo.servlet.pageBroker | BajaServlet | Fully-qualified class name of PageBroker
class to use. For example, oracle.cabo.servlet.xml.UIXPageBroker.
This initialization parameter must be specified for all applications
which use the UIX Controller. |
| oracle.cabo.servlet.defaultPage | AbstractPageBroker |
The name of the default Page to use
if no page name is specified in the requested URL.
|
| oracle.cabo.servlet.event.pageFlowEngine | AbstractPageBroker |
The fully qualified class name of the
PageFlowEngine to use.
If no PageFlowEngine is
specified, an instance of the
TrivialPageFlowEngine is
used.
|
| oracle.cabo.servlet.loginPage | TrivialPageFlowEngine |
The name of the Page to display
if login is required.
|
| oracle.cabo.servlet.loggedInKey | TrivialPageFlowEngine |
The name of the key to use to check whether the user is logged in.
If this key is set, the TrivialPageFlowEngine
checks the HttpSession object for a
value associated with this key. If a value is not found, the user is
forced to login on the page specified by the
oracle.cabo.servlet.loginPage
initialization parameter.
|
| oracle.cabo.ui.UIExtensions | BaseUIPageBroker |
A comma-separated list of fully-qualified class names. Each class
in the list must implement the UIExtension
interface. Each UIExtension will be
instantiated and registered by the
BaseUIPageBroker.
|
| oracle.cabo.image.servletURL | BaseUIPageBroker | An URL which specifies the location of a ImageServlet instance which should be used for any dynamic image generation requests. |
| oracle.cabo.image.headless | BaseUIPageBroker | A boolean parameter which disables dynamic image generation, intended to alleviate the X Server requirement in "headless" environments. If set to "true", UIX will never attempt to generate any images, and thus will never require an X Server connection. Images which already exist in the image cache continue to be be available. Defaults to "false". |
| oracle.cabo.servlet.xml.UIXPath | UIXPageBroker |
The full file system path to the directory containing UIX files.
If not specified, the UIXPageBroker
looks for UIX files on the web application path
(e.g., getRealPath()).
|
| oracle.cabo.servlet.xml.TemplateLibraries | UIXPageBroker | A comma-separated list of template library files; each will be loaded and automatically registered, so that developers don't need to explicitly specify them. |
| oracle.cabo.servlet.xml.XMLProvider | UIXPageBroker | The fully qualified class name of an implementation of the XMLProvider interface. If not specified, the Oracle XML Parser is used. |
| oracle.cabo.servlet.xml.checkModified | UIXPageBroker |
A boolean parameter used to enable or disable checks for
modifications to UIX files while the server is running.
When checkModified is set to "true", the
UIXPageBroker checks for
modifications to the underlying UIX document on every
request. This is particularly useful during development,
as it means that changes that you make to the UIX file
can be viewed simply by saving the file and refreshing
the browser. However, there is a slight impact on the
performance, as the time stamp of the UIX file must be
checked on every request. So, in production deployments,
checkModified should be set to "false" to avoid
unnecessary file system checks. Defaults to "true".
|
In the sample installations described in this chapter, we have favored ease of configuration over performance. One area which may be worthy of optimization is the use of the UIX installable resource files. These are the image, style sheet, JSP and JavaScript library files used by UIX. In our sample installations, we have used the simplest configuration, in which each web application owns its own copy of these files. Although this is a completely reasonable configuration, a more optimized solution would be to allow multiple web applications to share a single set of UIX installable resource files.
The most obvious reason for sharing the UIX resource files - reducing disk space usage - is probably the least significant from a performance perspective. More important is that sharing UIX resource files can actually reduce the number of HTTP requests that are made to your server, as it enables browsers and other caching technologies to avoid downloading and caching different copies of the same images, style sheets, etc. When each web application owns its own copy of the UIX resource files, the files are accessed by different URLs depending on which web application is being used. By sharing resources across web applications, browsers only need to download each resource file once for all applications that reference the shared resource.
Another advantage to reducing the number of copies of the UIX installable resource files is that it simplifies the migration process when upgrading to new versions of UIX. New versions of UIX are likely to introduce new images, styles, or JavaScript libraries, or may include enhancements or bug fixes to existing files. If each web application has a private copy of the UIX installable resource files, upgrading to new versions of UIX can be challenging. In the worst case scenario, every single WAR/EAR file would need to be repackaged and redeployed. Sharing a single copy of the UIX resource files across applications can greatly simplify the upgrade process.
This section describes several different ways to share the UIX installable resource files across multiple UIX applications.
In order to share the UIX resource files across multiple web applications, the files must be installed in some location where they can be accessed both by the web applications, as well as by a web browser. This usually leaves two possibilities. Since the resource files must be accessible by a web browser, the shared resources must either be installed in the servlet container, or when deploying the web application behind a web server, on the web server itself. When deploying the UIX installable resource files in a servlet container, perhaps the most obvious location for these files is in the root directory of the default web application.
In OC4J, the j2ee/home/default-web-app directory serves as the document root for the default web application. By installing the UIX resource files directly under j2ee/home/default-web-app, we can access these files via URLs which start with "/cabo". For example, if the UIX images are placed under the j2ee/home/default-web-app/cabo/images directory, they can be access with URLs which start with "/cabo/images". In Tomcat, the default web application is hosted in the webapps/Root directory.
After unzipping the uix2-install.zip file into the root directory of
the default web application, the next step is to
configure UIX to use these resources. By default, UIX looks for its
resources relative to the root directory of current web application.
However, this location can be explicitly overridden using the
Configuration API. In particular,
the ConfigurationImpl.putFullURIAndPath()
method can be used to specify a new URI and path for the UIX
resource files.
For example, assuming that we want to relocate the UIX resource files to
the /private/oc4j/j2ee/home/default-web-app/cabo directory, we can
make the following call to
ConfigurationImpl.putFullURIAndPath()
configImpl.putFullURIAndPath(Configuration.BASE_DIRECTORY,
"/cabo",
"/private/oc4j/j2ee/home/default-web-app/cabo");This call reconfigures UIX so that it will look for all resource files under /private/oc4j/j2ee/home/default-web-app/cabo. The URLs that UIX generates when referencing these files will start with "/cabo", for example "/cabo/images/error.gif".
Of course, the actual path to use is platform and machine dependent,
and as such well behaved web applications should not hardcode a
machine-specific path. One alternative is to allow the path to be set at
deployment time via a servlet initialization parameter. The following
sample PageBroker implementation shows
one way to implement this functionality.
import oracle.cabo.servlet.xml.UIXPageBroker;
import javax.servlet.Servlet;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import oracle.cabo.share.config.ConfigurationImpl;
import oracle.cabo.servlet.xml.UIXPageBroker;
public class CommonResourcePageBroker extends UIXPageBroker
{
/**
* Override of BaseUIPageBroker.createDefaultConfiguration().
*/
protected ConfigurationImpl createDefaultConfiguration()
{
ConfigurationImpl impl = super.createDefaultConfiguration();
// Get the init param value from the ServletConfig
ServletConfig config = getServlet().getServletConfig();
String path = config.getInitParameter(_PATH_KEY);
// If the path has been specified as an init param, reconfigure
// the Configuration object to use the specified path
if (path != null)
{
impl.putFullURIAndPath(impl.BASE_DIRECTORY, "/cabo", path);
}
return impl;
}
// Key for the common path servlet initialization parameter
private static final String _PATH_KEY = "demo.CommonResourcePath";
}
This sample PageBroker implementation
looks for a servlet initialization parameter with the name
"demo.CommonResourcePath". If this initialization parameter is
specified, the value is used as the path for the
Configuration.BASE_DIRECTORY.
We can update our "Hello, World!" application to use this sample
PageBroker and specify
the path to our shared resource files with a couple of minor
changes to our web.xml file. First, update the
PageBroker initialization parameter:
<init-param>
<param-name>oracle.cabo.servlet.pageBroker</param-name>
<param-value>CommonResourcePageBroker</param-value>
</init-param>Then, add a new parameter to specify the location of the UIX resources:
<init-param>
<param-name>demo.CommonResourcePath</param-name>
<param-value>/private/oc4j/j2ee/home/default-web-app/cabo</param-value>
</init-param>Exposing an initialization parameter in this manner provides a flexible way to allow the UIX resource files to be relocated. A new machine-specific location can be defined as needed at deployment time. However, an initialization parameter is not the only way to implement this capability. Other application-specific configuration mechanisms can be used with the same results.
Quite a bit of configuration work is required to set up a shared
deployment of the UIX resource files in the default web application.
To avoid this extra configuration work, UIX supports an alternate
mechanism for sharing the UIX resource files across web applications.
If a private copy of the UIX resource files is not found under the
current web application, UIX looks for a shared copy of the UIX
resource files under a web application which is bound to the
Configuration.BASE_DIRECTORY URI.
If a web application which contains
the UIX resource files is found at this URI, UIX automatically reconfigures
itself to use these shared files. In this case, the UIX installable
resource files can be shared across multiple applications without writing
any special configuration code.
If the current application does not contain its own copy of the UIX resource
files, UIX uses the Servlet API's
ServletContext.getContext() method to look
for another web application which contains the UIX installable resource files.
This method takes the base URI of the web application to look for, and if a web
application is found at the specified URI, returns the
ServletContext instance associated with the
web application. The ServletContext.getRealPath()
method can then be used to locate web application's contents (in our case, the
UIX installable resource files) on the file system.
UIX uses the ServletContext.getContext() method
to look for a web application which is bound the the
Configuration.BASE_DIRECTORY URI. By default,
the BASE_DIRECTORY URI is set to "/cabo",
although this value can be changed to using the
ConfigurationImpl.putRelativeURI() or
ConfigurationImpl.putFullURIAndPath()
methods. If UIX finds a web application which is bound to the
BASE_DIRECTORY URI, it checks to see if
this web application contains the UIX installable resource files. If
so, UIX automatically reconfigures itself to use these resource
files. For example, instead of generating URLs which reference files
under the current web application, such as "/greeting/cabo/images/t.gif" for
our sample application, UIX generates URLs which map directly to the
shared installable resource files, such as "/cabo/images/t.gif".
Any number of web applications can make use of the resource files deployed
in the shared web application, without writing any application-specific
configuration code or setting any initialization or configuration parameters.
Only two steps are required to enable this shared resource file deployment.
First, the resource files must be deployed in a web application which is
bound to the BASE_DIRECTORY URI
(typically "/cabo"). Then, any web application which is deployed in the
same servlet container can make use of these files simply by removing the
application's private copy of the UIX resource files. UIX takes care of the
rest.
The following steps describe how to deploy the UIX installable resource files to a web application in OC4J. These steps are essentially a subset of those in the Deploying UIX Applications in OC4J section.
We'll name our application UIXResourcesApp and create the application directory at j2ee/home/applications/UIXResourcesApp.
We'll use the following application.xml file for our UIX resources application:
<?xml version="1.0"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" "http://java.sun.com/dtd/application_1_3.dtd">
<application>
<display-name>UIXResourcesApp</display-name>
<module>
<web>
<web-uri>cabo</web-uri>
<context-root>/</context-root>
</web>
</module>
</application>
Note, we set the <web-uri> to "cabo", as
this is the URI/directory name that we will use for the web application
whic contains the UIX installable resource files.
To install the application.xml file, create a j2ee/home/applications/UIXResourcesApp/META-INF directory and copy the above contents into the application.xml file. As usual, if you are copying the contents from your browser into the application.xml file, be sure to remove any white space at the start of the file.
Unzip uix2-install.zip into the j2ee/home/applications/UIXResourcesApp directory. This should create the images, styles, jsps and jsLibs directories under j2ee/home/applications/UIXResourcesApp/cabo.
web.xml file
Create the j2ee/home/applications/UIXResourcesApp/cabo/WEB-INF directory
and copy the following contents into the web.xml file:
<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
<web-app>
</web-app>
Note that the web.xml file is basically empty. Although we don't define
any servlets, the web.xml file is required to deploy the web application.
Add the following entry to the server.xml file in the j2ee/home/config directory:
<application name="UIXResourcesApp"
path="{your path}/j2ee/home/applications/UIXResourcesApp"
auto-start="true"/>
Add the following element as a child of the <web-site> root element
in the j2ee/home/config/default-web-site.xml file:
<web-app application="UIXResourcesApp"
name="cabo"
root="/cabo"/>
Note: In order for UIX to be able to locate the UIX resource files,
the base URI that is used to bind the web application must exactly
match the name (and directory name) of the web application. For
example, if the URI for the
Configuration.BASE_DIRECTORY is set to "/uixi"
(for UIX installable files), then the following
binding is not sufficient:
<web-app application="UIXResourcesApp"
name="cabo"
root="/uixi"/>Although this binding is sufficient for providing access to the UIX installable files at the "/uixi" URI, UIX will not be able to locate the files on the file system. Instead, the UIX installable resource files must be placed in a web application/directory named "uixi", and the following binding must be used:
<web-app application="UIXResourcesApp"
name="uixi"
root="/uixi"/>If the name of the web application does not match the base URI that is used to bind the web application, UIX will not be able to locate the UIX installable resource files.
In our sample application, we installed the UIX resource files under the j2ee/home/applications/HelloWorldApp/HelloWorldWebApp/cabo/ directory. If the UIX resource files are found in this directory, this web application-specific copy of these files will be preferred over the shared copy. So, to use the shared UIX installable resource files in the "/cabo" web application, simply remove the cabo directory from our HelloWorldWebApp.
Once the UIX installable resource files are deployed in a web application
at the BASE_DIRECTORY URI, any new web
applications that are deployed to the same servlet engine instance can
use the shared installable files simply by not installing a private copy
of these files.
Although most servlet engines can themselves serve as both a servlet engine and a web server, quite often the servlet engine instance is deployed behind a web server. That is, incoming HTTP requests are first processed by the web server, and only those requests which are targeted at a servlet or JSP are directed to the servlet engine. In this configuration, another option for sharing UIX installable resource files is possible. The UIX resource files can be installed on the web server and shared across multiple applications running behind the same web server.
One advantage of deploying the UIX resource files on a web server is that this reduces the load on the servlet engine. The web server is responsible for what it does best - streaming data back to the browser. The servlet engine can spend time that would otherwise be spent streaming back image or style sheet data doing more important work, such as running your web applications.
When deploying behind a web server, the most obvious location for the UIX resource files is in the web server's document root. For example, when deploying behind Apache, the UIX installable resources can be installed into the Apache/htdocs/cabo directory. One advantage of placing the UIX resources in the document root of the web server is that the URLs used to access the resources are short. Since a single UIX page can contain many URLs to UIX resource files such as images, keeping these URLs short results in smaller HTML content.
When installing the UIX installable resource files on the web server, it is extremely important to make sure that the servlet engine has permission to access these directories. In general, if the servlet engine and web server are run using the same user id, this should not a problem. However, if different user ids are used to run these two different processes, it is possible that the servlet engine may not be able to access the files that are installed under the web server. In this case, you will need to change the file system permissions to make sure that both the web server and the servlet engine can access the UIX installable resource files. In addition, the servlet engine requires write access to the cabo/styles directory, as UIX dynamically creates style sheet files at runtime and stores these files under cabo/styles/cache.
Since the UIX can not use
ServletContext.getContext() to automatically
locate the UIX installable resource files when they are deployed on the
web server, an extra configuration step is required. The location of
the UIX installable resource files must be explicitly specified via
a "oracle.cabo.ui.sharedContextPath" system property. This property
specifies the parent directory which contains the UIX installable
resource files, under the
Configuration.BASE_DIRECTORY URI.
System properties are specified using on the command line using the "-D" parameter when starting the Java virtual machine. For example, if the UIX installable resource files are installed in "/private/oracle/Apache/Apache/htdocs/cabo", the following command should be used when starting OC4J:
java -Doracle.cabo.ui.sharedContextPath=/private/oracle/Apache/Apache/htodcs -jar oc4j.jar
UIX appends the URI associated with the
Configuration.BASE_DIRECTORY to the
path specified via the sharedContextPath property to determine
the full path to the UIX installable resource files.
As with the dedicated web application solution, UIX only uses the
shared copy of the UIX resource files if a local copy of these
files does not exist in the current web application. So, to allow
existing web applications to take advantage of the shared copy of the
UIX installable resource files, any private copies of these files
must be removed - with one important exception! When deploying the
UIX resource files behind a web server, a copy of the UIX JSP files,
which are normally found in the cabo/jsps directory, must always be
kept in each and every web application. This is true even if the
web server is capable of executing JSPs. The reason for this is
because the web application and the UIX JSPs share Java objects -
specifically Configuration instances.
If the UIX installable JSP files are deployed on the web server,
and thus in a separate Java VM, it is not possible to share
object instances between the JSPs and the web application.
Fortunately, this requirement is not quite as imposing as it might seem at first, since the UIX installable JSP files are guaranteed to never change. To simplify the upgrade process, the UIX JSP files are simply wrappers which call into Java code contained in the uix2.jar file. As such, any enhancements or bug fixes to the UIX JSPs can be made without making changes to the JSP files themselves. So, the UIX JSP files can be bundled into each web application/WAR file once, after which there is no need to ever pick up new versions of these files, since these files never change.
Once the UIX resource files (except the JSPs) are removed from the web application, UIX will automatically check the path specified via the oracle.cabo.ui.sharedContextPath system property. If the UIX installable resource files are found under this path, UIX will automatcially reconfigures itself to reference these files.