Oracle Help for the Web Developer's Guide	Contents	Previous	Next

Deploying OHW on OC4J Using the Deploy Bundle

One of the Oracle Help for the Web (OHW) release files available for downloading from the Oracle Technology Network (OTN) at http://www.oracle.com/technology/tech/java/help/ is the OHW deploy or unconfigured bundle. Unlike the demo bundle, the deploy bundle is not preconfigured for any Java servlet. The OHW deploy bundle contains only the optimized files for UIX and OHW that you need to deploy OHW help systems. Read this page if you want to configure OHW on Oracle Application Server Containers for J2EE (OC4J) using the deploy bundle. If you are deploying on Apache Tomcat, read Deploying OHW on Tomcat Using the Deploy Bundle.

This page contains the following sections:

Sample Server and Application Directory Structure
Installing and Testing OC4J
Downloading the OHW Deploy Bundle
Installing the OHW Servlet
Setting Up the J2EE Application for OHW
Setting Up the UIX Resources Application for OHW
Preparing the Directory Structure for the OHW Helpsets
Adding One or More Helpsets to the OHW Configuration File
Setting Up One or More Web Modules for OHW
Binding One or More Web Modules to the OHW Application
Viewing the OHW Help System on OC4J
Upgrading OHW and UIX
Deploying OHW Help Systems Using WAR/EAR Files

Sample Server and Application Directory Structure

The following demonstrates a typical directory structure that is consistent with a basic OC4J and OHW installation. Use this sample directory as a guide when following the instructions in the rest of this page.

Server configuration:

  +---<mypath>
  |+----j2ee
  ||+-----home
  |||+------config
  ||||--------server.xml
  ||||--------http-web-site.xml
  |.....
  |||+------lib
  ||||--------ohw.jar
  ||||--------uix2.jar
  ||||--------regexp.jar
  ||||--------share.jar
  |.....
  |+----lib
  ||------xmlparserv2.jar
  |.....

Application configuration:

  +---<mypath>/j2ee/home/applications
  |
  |+----ohw-eapp
  ||+-----META-INF
  |||+------application.xml
  ||+-----project_one
  |||+------cabo (automatically generated at runtime)
  |||+------helpsets
  ||||--------ohwconfig.xml
  ||||+-------Tutorial
  |||||---------OHW help content/images and control files
  ||||+-------UserGuide
  |||||---------OHW help content/images and control files
  |||+------jsLibs
  ||||--------OHW JavaScript files
  |||+------WEB-INF
  ||||--------web.xml
  ||+-----project_two
  |||+------cabo (automaticallygenerated at runtime)
  |||+------helpsets
  ||||--------ohwconfig.xml
  ||||+-------GettingStarted
  |||||---------OHW help content/images and control files
  |||+------jsLibs
  ||||--------OHW JavaScript files
  |||+------WEB-INF
  ||||--------web.xml
  |
  |+----uixresources-eapp
  ||+-----META-INF
  |||+------application.xml
  ||+-----cabo
  |||+------images
  |||+------jsLibs
  |||+------jsps
  |||+------styles
  ||||+-------cache
  |||+------WEB-INF
  ||||--------web.xml
  |.....

Installing and Testing OC4J

OC4J can be run in either standalone mode or in combination with an HTTP server. In standalone mode, URLs are sent directly to OC4J. In combination with an HTTP server, the URLs are sent to the HTTP server, which is configured to forward HTTP requests from certain URLs to OC4J. This section discusses OC4J standalone mode only. Additional information for configuring OC4J with the Oracle HTTP Server can be found in the Oracle Application Server Containers for J2EE User's Guide.

You can download the latest version of OC4J standalone from OTN at the URL http://www.oracle.com/technology/tech/java/oc4j/content.html.

Note: The commands listed below assume that you have the Java2 SDK binaries in your path setting for your system. If you are not able to run the java and jar executable from the command line then please follow the documentation provided by the Java2 SDK to resolve this. (JDK 1.3.1 is recommended).

After downloading the OC4J zip file (oc4j_extended.zip), install OC4J by following these steps:

Unzip oc4j_extended.zip in any directory on the server.

This creates the OC4J directory structure and files under the <mypath>/j2ee/home directory (e.g., <mypath>/j2ee/home/applications, <mypath>/j2ee/home/config, etc.).
Run the OC4J install command from a console window.

Using a DOS shell or UNIX terminal, change the current directory to the <mypath>/j2ee/home directory and run the following command:
```
java -jar oc4j.jar -install
```
Enter a password for the admin user when prompted. You will need this password later for administrative tasks.
Test the installation.

From the <mypath>/j2ee/home directory, run the following command to start OC4J:
```
java -jar oc4j.jar
```
You should see some output that indicates OC4J has started, such as "Oracle Application Server <version> Containers for J2EE initialized."
To verify that the OC4J installation is working correctly, point your browser to:

http://localhost:8888/

Depending on your browser proxy configuration settings, you might have to specify the complete domain name of the machine that is hosting OC4J, for example:

http://<yourhost.domain.com>:8888/

If the OC4J installation is successful, you should see a welcome page in the browser, such as "Oracle Application Server Containers for J2EE <version> - Up and running."

To stop OC4J, run the following command from the <mypath>/j2ee/home directory:

java -jar admin.jar ormi://localhost:23791 admin <password> <your admin password> -shutdown

The password entered here must be the same pasword you entered when installing OC4J.

To start OC4J, run the following command from the <mypath>/j2ee/home directory:

java -jar oc4j.jar

For information on administering the server using the admin.jar command-line tool, see the Oracle Application Server Containers for J2EE User's Guide.

Downloading the OHW Deploy Bundle

For the latest information, check any download and install instructions that may be available on the OHW download page.

Download the OHW deploy bundle from OTN at http://www.oracle.com/technology/tech/java/help/. The name of the the deploy bundle file is ohw-deploy-nnn.zip, where nnn is the OHW release number (e.g., ohw-deploy-1_1_1.zip). This file includes OHW, sample helpsets, and the OC4J servlet engine.

Unzip the ohw-deploy-nnn.zip file in a temporary directory. This unzips the following files:

   ohw.jar
   regexp.jar
   share.jar
   uix2.jar
   xmlparserv2.jar
   ohw-install.zip
   uix2-install.zip
   ohwconfig.xml
   web.xml

Installing the OHW Servlet

The instructions in this section assume you have installed OC4J and downloaded the ohw-deploy-nnn.zip file from OTN. If you have not done so, see Installing and Testing OC4J and Downloading the OHW Deploy Bundle.

Copy the following JAR files from ohw-deploy-nnn.zip into <mypath>/j2ee/home/lib.
```
   ohw.jar
   regexp.jar
   share.jar
   uix2.jar
```
If the JAR file xmlparserv2.jar does not exist in <mypath>/lib, copy the file from ohw-deploy-nnn.zip into the directory.

When you installed OC4J, xmlparserv2.xml should have already been created in <mypath>/lib.

Setting Up the J2EE Application for OHW

This section describes how to set up the J2EE application for OHW on OC4J. The instructions here assume you have installed OC4J. If you have not done so, see Installing and Testing OC4J.

Create the following directories for the OHW application under <mypath>j2ee/home/applications.

 <mypath>/j2ee/home/applications/ohw-eapp
 <mypath>/j2ee/home/applications/ohw-eapp/META-INF

Add the OHW application to the OC4J server configuration file, server.xml. This defines the name and location of the OHW application. The server.xml file also defines any *-web-site.xml files for the web modules.

In an editor, open the server.xml file in <mypath>/j2ee/home/config and modify the <application-server></application-server> section to add the OHW application information.

File location: <mypath>/j2ee/home/config/server.xml

Sample edit and usage:

<application name="ohw-eapp" path="../applications/ohw-eapp" auto-start="true" />

Attribute	Description
`application name`	Any name.
`path`	Path to J2EE application, relative to server.xml (or path and name of .war file).
`auto-start`	Starts automatically when OC4J starts. Should be set to "true".

Note: For WAR/EAR file-based deployment, see Deploying OHW Help Systems Using WAR/EAR Files.

Sample server.xml file


 <?xml ... >
 <!DOCTYPE ... >

 <application-server application-directory="../applications"
  deployment-directory="../application-deployments">
   <library path="../tools.jar" />
   <rmi-config path="./rmi.xml" />
   ...
   <global-application name="default" path="application.xml" />
   <application name="ohw-eapp" path="../applications/ohw-eapp" auto-start="true" />
   <global-web-app-config path="global-web-application.xml" />
   <web-site path="./http-web-site.xml" />
   ...
 </application-server>

Setting Up the UIX Resources Application for OHW

OHW includes a set of UIX installable resource files that can be shared by multiple web modules. These are the image, stylesheet, JSP, and JavaScript library files used by UIX to create the OHW UI. This section describes how to set up the UIX resources application for OHW on OC4J, so that multiple web modules in the same OC4J container can share a single copy of the UIX installable resource files.

Note: In OHW releases prior to 1.0.8 and 1.1.x, each web module had a private copy of the UIX installable resource files.

By creating a separate UIX resources application with its own URL that can be used by other applications in the same <mypath>/j2ee/home directory, you can avoid duplicating the UIX installable resources for each web module. This not only reduces disk space usage and simplifies the UIX upgrade process, but it can actually reduce the number of HTTP requests that are made to the server.

Sharing a single set of UIX installable resource files enables browsers and caching technologies to avoid downloading and caching different copies of the UIX image, stylesheet, JSP, and JavaScript library files. When each web module has a private copy of the UIX installable resource files, the files are accessed by different URLs depending on the application module being used. By sharing the resource files across multiple web modules, the browsers only need to download each resource file once for all applications that reference the shared resource.

More information about sharing UIX installable resource files is found in the "Installation" chapter of the UIX Developer's Guide, which is available in the JDeveloper online help, with the UIX download bundles, and in the JDeveloper documentation on OTN at http://helponline.oracle.com/jdeveloper/help/.

The following steps describe how to deploy the UIX installable resource files to a web application on OC4J.

Note: If you are copying the sample XML file contents from your browser into your XML file, be sure to remove any white space at the start of the file.

Create the following directories for the UIX Resources application under <mypath>j2ee/home/applications.

 <mypath>/j2ee/home/applications/uixresources-eapp
 <mypath>/j2ee/home/applications/uixresources-eapp/META-INF

Install the application.xml file in the directory <mypath>/j2ee/home/applications/uixresources-eapp/META-INF to define the UIX web module.

In an editor, copy the following contents in the application.xml file.

File location: <mypath>/j2ee/home/applications/uixresources-eapp/META-INF/application.xml

Sample application.xml file for UIX Resources:
```
 <?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>uixresources-eapp</display-name>
   <module>
     <web>
       <web-uri>cabo</web-uri>
       <context-root>/</context-root>
     </web>
   </module>

 </application>
```
Note: <web-uri> is set to "cabo", as this is the URI/directory name for the web module that contains the UIX installable resource files. <context-root> is the root of the web module. It is usually "/" when the web module files are deployed in a directory.
Unzip uix2-install.zip (from ohw-deploy-nnn.zip) into the <mypath>/j2ee/home/applications/uixresources-eapp directory.

This should create the cabo directory and install the images, styles, jsps, and jsLibs subdirectories under <mypath>/j2ee/home/applications/uixresources-eapp, for example:
```
  <mypath>/j2ee/home/applications/uixresources-eapp/cabo/images/<files>
  <mypath>/j2ee/home/applications/uixresources-eapp/cabo/jsLibs/<files>
  <mypath>/j2ee/home/applications/uixresources-eapp/cabo/jsps/<files>
  <mypath>/j2ee/home/applications/uixresources-eapp/cabo/styles/<files>
```
Install the web.xml file for the UIX web module.

Create the <mypath>/j2ee/home/applications/uixresources-eapp/cabo/WEB-INF directory and copy the following contents into the web.xml file:

Sample web.xml file for UIX web module:
```
 <?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, but it is required to deploy the UIX web module.

Add the UIX resources application to the OC4J server configuration file, server.xml.

In an editor, open the server.xml file in <mypath>/j2ee/home/config and modify the <application-server></application-server> section to add the UIX resources application information.

File location: <mypath>/j2ee/home/config/server.xml

Sample edit:

 <application name="uixresources-eapp" path="../applications/uixresources-eapp" auto-start="true" />

Sample server.xml file


 <?xml ... >
 <!DOCTYPE ... >

 <application-server application-directory="../applications"
  deployment-directory="../application-deployments">
   <library path="../tools.jar" />
   <rmi-config path="./rmi.xml" />
   ...
   <global-application name="default" path="application.xml" />
   <application name="ohw-eapp" path="../applications/ohw-eapp" auto-start="true" />
   <application name="uixresources-eapp" path="../applications/uixresources-eapp" auto-start="true" />
   <global-web-app-config path="global-web-application.xml" />
   <web-site path="./http-web-site.xml" />
   ...
 </application-server>

Bind the web module access location to the UIX resources application in the http-web-site.xml configuration file.

In and editor, open the http-web-site.xml file and add the UIX web module access location as a child of the <web-site> root element.

File location: <mypath>/j2ee/home/config/http-web-site.xml

Sample edit and usage:

 <web-app application="uixresources-eapp" name="cabo" root="/cabo" />

Attribute	Description
`application`	J2EE application name for UIX installable resources to which the web module will be bound. Should match the application name in server.xml (see Step 5).
`name`	Name of UIX web module. Indicates the path to the directory containing the `cabo` files. Should match the web-uri name in Step 2.
`root`	Name to be used in the URL. The root URL can be different from name.

Sample http-web-site.xml file


 <?xml version="1.0"?>
 <!DOCTYPE web-site PUBLIC "Orion Web-site" "http://xmlns.oracle.com/ias/dtds/web-site.dtd">

 <web-site port="8888" display-name="Default Oracle Application Server Containers for J2EE Web Site">
   <default-web-app application="default" name="defaultWebApp" />
   ...
   ...
   <web-app application="uixresources-eapp" name="cabo" root="/cabo" />
   <access-log path="../log/http-web-access.log" />
 </web-site>

Remove all private copies of the UIX installable resource files, if they have been installed.

Any web modules that are deployed to the same servlet engine instance can use the shared UIX installable resource files simply by not installing a private copy of these files.

Preparing the Directory Structure for the OHW Helpsets

The instructions here assume you have set up the OHW application. If you have not done so, see Setting Up the J2EE Application for OHW.

Follow these steps to prepare the directory structure for deploying one or more OHW help systems:

For each help system, create the following web module directories under <mypath>j2ee/home/applications/ohw-eapp.
```
 <mypath>/j2ee/home/applications/ohw-eapp/project_one/helpsets
 <mypath>/j2ee/home/applications/ohw-eapp/project_one/WEB-INF
```
Ordinarily--and for convenience--your project helpsets are installed in or under the helpsets directory.

If you have two large help systems, each with several helpsets, you may want to create a web module directory for each help system. For example, if you have two help systems, project_one and project_two, you could create the following:
```
 <mypath>/j2ee/home/applications/ohw-eapp/project_one/helpsets
 <mypath>/j2ee/home/applications/ohw-eapp/project_one/WEB-INF
 <mypath>/j2ee/home/applications/ohw-eapp/project_two/helpsets
 <mypath>/j2ee/home/applications/ohw-eapp/project_two/WEB-INF
```
For each web module, place the help content files and control files that make up your OHW help system in the helpsets directory or, if you prefer, create subdirectories in helpsets for the files.

For example, if you have two helpsets--Tutorial and UserGuide--for a web module, you might create the following:
```
  <mypath>/j2ee/home/applications/ohw-eapp/project_one/helpsets/Tutorial
  <mypath>/j2ee/home/applications/ohw-eapp/project_one/helpsets/UserGuide
```
Helpsets in a web module can be merged at runtime, so multiple authors can create multiple helpsets that will be seamlessly merged. The merging behavior is specified by attributes in the OHW configuration file (by default, ohwconfig.xml).

Regardless of your setup, place all the help files in the helpsets directory, including the helpset file, help topic (HTML) files, and the other control files (index, table of contents, etc.). For more information about control files, see Oracle Help File Formats. Also, place any JAR files, if you are using jar files for your helpset. (You can use JARred and unJARred helpsets together in the same deployment.)

Note: By default OHW automatically processes help topic HTML files that are located in the same locations as the helpset files. See OHW Configuration File to learn more about using remote locations for help topic HTML files.
For each web module (i.e., project_one), unzip ohw-install.zip (from ohw-deploy-nnn.zip) into the <mypath>j2ee/home/applications/ohw-eapp/project_one web module directory.

This creates a subdirectory called jsLibs and places OHW JavaScript files into the subdirectory, e.g.,
```
  <mypath>/j2ee/home/applications/ohw-eapp/project_one/jsLibs/<files>
```
(Optional) For each web module (i.e., project_one), unzip uix2-install.zip (from ohw-deploy-nnn.zip) into the <mypath>/j2ee/home/applications/ohw-eapp/project_one web module directory.

This creates the cabo subdirectory structure and places sharable UIX installable resource files such as images, JavaScripts, JSPs, and style sheets into these directories:
```
  <mypath>/j2ee/home/applications/ohw-eapp/project_one/cabo/images/<files>
  <mypath>/j2ee/home/applications/ohw-eapp/project_one/cabo/jsLibs/<files>
  <mypath>/j2ee/home/applications/ohw-eapp/project_one/cabo/jsps/<files>
  <mypath>/j2ee/home/applications/ohw-eapp/project_one/cabo/styles/<files>
  
```
Note: This is the simplest directory setup, in which each web module owns a private copy of the UIX installable resource files. For a more optimized solution, where multiple web modules share a single copy of the UIX files, see Setting Up the UIX Resources Application for OHW.

Adding One or More Helpsets to the OHW Configuration File

The instructions here assume you have installed the OHW help content files and control files in the helpsets directory. If you have not done so, see Preparing the Directory Structure for the OHW Helpsets.

The ohwconfig.xml is the only non-OC4J configuration file. Among other things, this file tells OHW where to find your helpsets. Once set up, the ohwconfig.xml file will usually not need editing. Sometimes a refresh of help content will include additional helpsets, which you will then have to specify.

Follow these steps to add one or more helpsets to the OHW configuration file:

Place the ohwconfig.xml file (from ohw-deploy-nnn.zip file) into the <mypath>/j2ee/home/applications/ohw-eapp/project_one/helpsets directory.

In an editor, open the ohwconfig.xml file and specify the location of your helpsets and help topic HTML files in the <books></books> section.

The <books> element can contain any number of helpsets or helpbooks, or a combination of both. Helpsets can be merged at runtime, so multiple authors can create multiple helpsets that will be seamlessly merged. The merging behavior is specified by the attributes combineBooks and useLabelInfo. The <helpSet> element can contain zero or more <contentLocation> elements, when Oracle Help help topic HTML files are located in locations other than those expected by Oracle Help. The <contentLocation> element is then used to specify the root location of a set of help topic HTML files. For more information about the elements in the ohwconfig.xml file, see OHW Configuration File.

File location: j2ee/home/applications/ohw-eapp/project_one/helpsets/ohwconfig.xml

Sample edit and usage:

 <books combineBooks="true" useLabelInfo="true">
   <helpSet jar="UserGuide/project_one.jar" location="project_one.hs" />
   <helpSet location="Tutorial/overview.hs" />
     <contentLocation baseURI="http://www.myCompany.com/help/" />
   </helpSet>
 </books>

Attribute	Description
`combineBooks`	"true" means to combine helpsets in one set of navigators (tabs), including Table of Contents and Index, at runtime.
`useLabelInfo`	"true" means author-defined labels are used for the navigators (tabs) of merged helpsets/helpbooks.
`jar`	Path to .jar file relative to ohwconfig.xml. OHW does not require that its contents be stored in .jar files, but most products do this to simplify file management.
`location`	Location of the .hs helpset definition file. Location is relative to the top of the .jar file if a .jar file is used. Otherwise, it is relative to the ohwconfig.xml file.
`baseURI`	An absolute URI to the root location of a set of help content. This can be files in another location or even on another web server.

Sample ohwconfig.xml file

 <helpConfiguration>

   <branding>
     ...
   </branding>

   <localeSettings>
     ...
   </localeSettings>

   <books combineBooks="false" useLabelInfo="true">
     <helpSet jar="UserGuide/project_one.jar" location="project_one.hs" />
     <helpSet location="Tutorial/overview.hs" />
       <contentLocation baseURI="http://www.myCompany.com/help/" />
     </helpSet>
   </books>

   <parameters>
    ...
   </parameters>

 </helpConfiguration>

Setting Up One or More Web Modules for OHW

The instructions in this section assume you have created a web module directory for your OHW help system. If you have not done so, see Preparing the Directory Structure for the OHW Helpsets and Adding One or More Helpsets to the OHW Configuration File.

Do the following to set up one or more web modules for deployment on OC4J:

For each web module, add the web module information to the OC4J configuration file, application.xml. This defines the path to where the web module files are deployed.

A sample application.xml file is included in ohw-demo-nnn.zip. You could copy and modify this file or create your own (see sample file below).

In an editor, create or open the application.xml file in <mypath>/j2ee/home/applications/ohw-eapp/META-INF and add a <module></module> section for each web module.

File location: <mypath>/j2ee/home/applications/ohw-eapp/META-INF/application.xml

Sample edit and usage:

 <module>
   <web>
     <web-uri>project_one</web-uri>
     <context-root>/</context-root>
   </web>
 </module>

Attribute	Description
`web-uri`	Path to web module from J2EE application (or name of .war file).
`context-root`	Root of the web module. Usually "/" when web module files are deployed in a directory.

Note: For WAR/EAR file-based deployment, see Deploying OHW Help Systems Using WAR/EAR Files.

Sample application.xml file

 <?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>ohw-eapp</display-name>

   <module>
     <web>
       <web-uri>project_one</web-uri>
       <context-root>/</context-root>
     </web>
   </module>

   <module>
     <web>
       <web-uri>project_two</web-uri>
       <context-root>/</context-root>
     </web>
   </module>

 </application>

For each web module, place the web.xml file (from ohw-deploy-nnn.zip) into the <mypath>/j2ee/home/applications/ohw-eapp/project_one/WEB-INF directory.

This sample servlet configuration file can be used without modification, as long as the ohwconfig.xml file is in the <mypath>/j2ee/home/applications/ohw-eapp/project_one/helpsets directory. Optionally, you can create the web.xml file yourself.

File location: j2ee/home/applications/ohw-eapp/project_one/WEB-INF/web.xml

Sample usage:

 <init-param>
   <param-name>configFileName</param-name>
   <param-value>/helpsets/ohwconfig.xml</param-value>
 </init-param>

Attribute	Description
`param-name`	configFileName is a parameter name used by OHW. Do not change.
`param-value`	Path from the web module to the ohwconfig.xml file, relative to the servlet context path. For most users, Oracle recommends that you do not modify this parameter.

Sample usage:

 <servlet-mapping>
   <servlet-name>OHW</servlet-name>
   <url-pattern>/</url-pattern>
 </servlet-mapping>

Attribute	Description
`servlet-name`	The OHW servlet to which the url-pattern applies. Do not change.
`url-pattern`	The URLs that are directed to the OHW servlet. For example, if the web module name = project_one and the url-pattern = /help/*, then the URL that accesses OHW would be http://myname.oracle.com:8888/project_one/help/

Sample 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>

   <login-config>
     <auth-method>BASIC</auth-method>
   </login-config>

   <servlet>

     <servlet-name>OHW</servlet-name>
     <servlet-class>oracle.help.OHW</servlet-class>

     <init-param>
       <param-name>configFileName</param-name>
       <param-value>/helpsets/ohwconfig.xml</param-value>
     </init-param>

   </servlet>

   <servlet-mapping>
     <servlet-name>OHW</servlet-name>
     <url-pattern>/help/*</url-pattern>
   </servlet-mapping>

 </web-app>

Repeat Steps 1 and 2 for additional web modules

Binding One or More Web Modules to the OHW Application

The instructions in this section assume you have defined one or more web modules for your OHW help system. If you have not done so, see Preparing the Directory Structure for OHW Helpsets, Adding One or More Helpsets to the OHW Configuration File and Setting Up One or More Web Modules for OHW.

Follow these steps to bind one or more web modules to the OHW application:

For each web module, bind the web module access location to the OHW application in the http-web-site.xml file.

In an editor, open http-web-site.xml located in <mypath>/j2ee/home/config and add the following line for each web module:


 <web-app application="ohw-eapp" name="project_one" root="/project_one" />

File location: j2ee/home/config/http-web-site.xml

Sample edit and usage:

 <web-app application="ohw-eapp" name="project_one" root="/project_one" />

Attribute	Description
`application`	J2EE application name for OHW to which the web module will be bound. Should match the application name in server.xml (see Step 2 of Setting Up the J2EE Application for OHW).
`name`	Name of web module (or name of .war file). Indicates the path to the directory containing the web module files. Should match the web-uri name in Step 1 of Setting Up One or More Web Modules for OHW.
`root`	Name to be used in the URL. The root URL can be different from name.

Note: For WAR/EAR file-based deployment, see Deploying OHW Help Systems Using WAR/EAR Files.

Sample http-web-site.xml file

 <?xml version="1.0"?>
 <!DOCTYPE web-site PUBLIC "Orion Web-site" "http://xmlns.oracle.com/ias/dtds/web-site.dtd">

 <web-site port="8888" display-name="Default Oracle Application Server Containers for J2EE Web Site">
   <default-web-app application="default" name="defaultWebApp" />
   <web-app application="ohw-eapp" name="project_one" root="/project_one" />
   <web-app application="ohw-eapp" name="project_two" root="/project_two" />
   <web-app application="uixresources-eapp" name="cabo" root="/cabo" />
   <access-log path="../log/http-web-access.log" />
 </web-site>

Viewing the OHW Help System on OC4J

Note: Make sure you have the JAVA_HOME environment variable set to a directory on the host where a version of JDK 1.2.2 or later resides (JDK 1.3.1 is recommended).

To see your help system in OHW, do the following:

Start the servlet engine, as described in Installing and Testing OC4J. If OC4J is already running, you must shut it down and then restart it before you can see the changes made since you last started the servlet.
Direct your browser to http://<hostname>:8888/project_one/help/ or http://<hostname>:8888/project_two/help/ where <hostname> is the name of the machine on which OC4J and OHW are installed.

If you are viewing OC4J from the same computer on which it is installed, you may be able to use the URL http://localhost:8888/project_one/help/, depending on your browser configuration.

The first page of the help system displays in the browser. If there is more than one helpset, use the drop down list in the toolbar to select a helpset, then click the helpset switcher to display the table of contents and index from the selected helpset only. The text search will search only for items in the selected helpset.

If you don't see the page as expected, check the console window for any error messages logged by OC4J. OC4J also logs error messages to the log files under <mypath>/j2ee/home/log.

Changing the OHW Access URL

As seen in the section Viewing the OHW Help System on OC4J above, the URL to access the OHW help system is http://<hostname>:8888/project_one/help/, where <hostname> is the name of the machine on which OHW and OC4J are installed.

You can change this URL in the following ways:

Change the "help" at the end of the URL
Change the "project_one" name to another name

Changing the "help" at the end of the URL

Edit the web.xml file in <mypath>/j2ee/home/applications/ohw-eapp/project_one/WEB-INF to change the "help" at the end of the URL.

Sample 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>

    <servlet>

       <servlet-name>OHW</servlet-name>
       <servlet-class>oracle.help.OHW</servlet-class>

       <init-param>
          <param-name>configFileName</param-name>
          <param-value>/helpsets/ohwconfig.xml</param-value>
       </init-param>

    </servlet>

    <servlet-mapping>
       <servlet-name>OHW</servlet-name>
       <url-pattern>/help/*</url-pattern>
    </servlet-mapping>

 </web-app>

The <servlet-mapping> parameter <url-pattern> specifies the URL used to access OHW. For example, if you change <url-pattern> from the default /help/* to /onlinereference/*, the URL used to access OHW would be http://<hostname>:8888/project_one/onlinereference/.

Changing "project_one" to another name

Edit the http-web-site.xml file in <mypath>/j2ee/home/config to change the "project_one" name to another name.

Sample http-web-site.xml file

 <?xml version="1.0"?>
 <!DOCTYPE web-site PUBLIC "Orion Web-site" "http://xmlns.oracle.com/ias/dtds/web-site.dtd">

 <web-site port="8888" display-name="Default Oracle Application Server Containers for J2EE Web Site">
   <default-web-app application="default" name="defaultWebApp" />
   <web-app application="ohw-eapp" name="project_one" root="/project_one" />
   <web-app application="ohw-eapp" name="project_two" root="/project_two" />
   <access-log path="../log/http-web-access.log" />
 </web-site>

root="/project_one" specifies the name you would use in the URL, e.g., http://<hostname>:8888/project_one/help/.

If you want the OHW access URL to be http://<hostname>:8888/developer/help/, you would modify root="/project_one" to root="/developer".

Upgrading OHW and UIX

Check the OHW download page for the latest download and install instructions before upgrading your OHW/OC4J installation.

Note: Stop the OC4J/OHW instance before upgrading. Restart OC4J/OHW after upgrading OHW and UIX.

To upgrade OHW to a newer version, you need to replace the OHW and UIX JAR files, and the OHW JavaScript files (distributed in ohw-install.zip). Do the following to upgrade OHW:

Repeat the steps in Installing the OHW Servlet, above. This updates the OHW and UIX JAR files.
Repeat Step 3 in Preparing the Directory Structure for the OHW Helpsets, above. This unzips files from ohw-install.zip and updates the files in the jsLibs directory of the web module, e.g., <mypath>/j2ee/home/applications/ohw-eapp/project_one/jsLibs.

To upgrade UIX, you need to replace the UIX installable resource files (distributed in uix2-install.zip). To upgrade the UIX installable resource files to a newer version, do one of the following:

If the OHW/OC4J server installation is using shared UIX installable resource files, repeat Step 3 in Setting Up the UIX Resources Application for OHW, above. This unzips files from uix2-install.zip into the cabo directory of the UIX resources application, e.g., <mypath>/j2ee/home/applications/uixresources-eapp/cabo.

Note: Remember to delete the runtime cache directory, e.g., <mypath>/j2ee/home/applications/ohw-eapp/project_one/cabo.
If each web module has a private copy of the UIX installable resource files, repeat Step 4 in Preparing the Directory Structure for the OHW Helpsets, above. This unzips files from uix2-install.zip into the cabo directory of the web module, e.g., <mypath>/j2ee/home/applications/ohw-eapp/project_one/cabo.

Deploying OHW Help Systems Using WAR/EAR Files

OC4J allows OHW web modules to be compressed as WAR (Web ARchive) files. The entire OHW application is then deployed as an EAR (Enterprise ARchive) file, which wraps any WAR and JAR files. You create WAR and EAR files using the standard Java JAR utility. The instructions in this section assume you have installed OC4J, OHW, and your OHW help files, tested your installation, and are ready to create the WAR/EAR files.

Note: In OC4J standalone, you can use the admin.jar command-line tool to deploy applications archived in the EAR format. See the Oracle Application Server Containers for J2EE User's Guide for details. For users of Oracle9iAS 9.0.x in a production environment, you must use Oracle Enterprise Management (OEM) for deployment. Refer to the Oracle9i Application Server Administrator's Guide and Oracle Enterprise Manager Administrator's Guide for information.

The following shows the directory structure for archiving OHW web modules into an EAR file for deployment to OC4J.

Directory Structure

  +---<mypath>
  |+----j2ee
  ||+-----home
  |||+------config
  ||||--------server.xml
  ||||--------http-web-site.xml
  |.....
  |.....
  |.....

  +---<mypath>/j2ee/home/applications
  |+----ohw-eapp
  ||+-----META-INF
  |||+------application.xml
  |||-----project_one.war
  |||-----project_two.war
  ||+-----project_one
  |||+------cabo (generated at runtime)
  |||+------helpsets
  ||||--------ohwconfig.xml
  ||||+-------Tutorial
  |||||---------OHW help content/images and control files
  ||||+-------UserGuide
  |||||---------OHW help content/images and control files
  |||+------jsLibs
  ||||--------OHW JavaScript files
  |||+------WEB-INF
  ||||--------web.xml
  ||+-----project_two
  |||+------cabo (generated at runtime)
  |||+------helpsets
  ||||--------ohwconfig.xml
  ||||+-------GettingStarted
  |||||---------OHW help content/images and control files
  |||+------jsLibs
  ||||--------OHW JavaScript files
  |||+------WEB-INF
  ||||--------web.xml
  |.....

Follow these instructions to deploy your OHW help system using WAR/EAR files.

Make sure you delete any files that are not required for deployment, especially the cabo/images/cache subdirectories that are automatically created for each web module during runtime testing.
Create a WAR file for each web module. The .war file should be created at the top of the web module. In the web module root, issue the command:
```
 % jar cvfM ../project_one.war *
```
The M option suppresses the creation of a manifest (.MF) file. The manifest file is not required because the OC4J configuration file (application.xml) serves as the manifest file. The .war file will include the entire contents of the web module, e.g., all files and all subdirectories under the project_one directory.
Repeat Step 2 for all other web modules under the ohw-eapp directory.
Place the .war files in the OHW application root (ohw-eapp).

The following shows the directory structure for archiving the OHW application into an EAR file for deployment to OC4J.

Archive Directory Format
```
    +---ohw-eapp
    ¦ +---META-INF
    ¦ ¦ +--application.xml
    ¦ +---project_one.WAR
    ¦ +---project_two.WAR
```

Modify the file application.xml. Add the .war file names to the application.xml file located in <mypath>/j2ee/home/applications/ohw-eapp/META-INF.

Typically, the .war file is placed at the top level of the application (not the web module) with a <context-root> that points to the top of the web module.

Sample edit:

 <application>
   <display-name>ohw-eapp</display-name>
   <module>
     <web>
       <web-uri>project_one.war</web-uri>
      <context-root>/project_one</context-root>
     </web>
   </module>
   <module>
     <web>
       <web-uri>project_two.war</web-uri>
      <context-root>/project_two</context-root>
     </web>
   </module>
 </application>

Create an .ear file for the entire OHW application. In the OHW application root, issue the following command:
```
 % jar cvfM ../ohw.ear *.war META-INF/application.xml
```
The M option suppresses the creation of a manifest (.MF) file. The manifest file is not required because the OC4J configuration file (application.xml) serves as the manifest file. Typically, the .ear file will be placed at the entry point for all web applications, as determined in the server.xml file.

The application .ear file (ohw.ear) will contain the .war files for all of the web modules as well as the META-INF directory and its application.xml file.

Modify the http-web-site.xml file. Add the .war file names to the http-web-site.xml file located in <mypath>/j2ee/home/config.

Sample edit:

 <?xml version="1.0"?>
 <!DOCTYPE web-site PUBLIC "Orion Web-site" "http://xmlns.oracle.com/ias/dtds/web-site.dtd">

 <web-site port="8888" display-name="Default Oracle Application Server Containers for J2EE Web Site">
   <default-web-app application="default" name="defaultWebApp" />
   <web-app application="ohw-eapp" name="project_one" root="/project_one" />
   <web-app application="ohw-eapp" name="project_two" root="/project_two" />
   <web-app application="uixresources-eapp" name="cabo" root="/cabo" />
   <access-log path="../log/http-web-access.log" />
 </web-site>

Modify the file server.xml. Add the following application entry to the server.xml file located in <mypath>j2ee/home/config.

Sample edit:


 <?xml ... >
 <!DOCTYPE ... >

 <application-server application-directory="../applications"
  deployment-directory="../application-deployments">
   <library path="../tools.jar" />
   <rmi-config path="./rmi.xml" />
   ...
   <global-application name="default" path="application.xml" />
   <application name="ohw-eapp" path="../applications/ohw.ear" auto-start="true" />
   <application name="uixresources-eapp" path="../applications/uixresources-eapp" auto-start="true" />
   <global-web-app-config path="global-web-application.xml" />
   <web-site path="./http-web-site.xml" />
   ...
 </application-server>

At runtime, OC4J will detect a new or changed .ear file and uncompress it. It will then uncompress all of the .war files into their correct web module directories. More information on the use of .war and .ear files in OC4J is available in the Oracle Application Server Containers for J2EE User's Guide.