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

Deploying OHW on Tomcat Using the Deploy Bundle

Tomcat is a Java servlet engine developed by the Jakarta Project of the Apache Software Foundation (http://jakarta.apache.org/). The latest version of Tomcat, Tomcat 4.0, supports the 2.3 version of the Servlet API. This section tells how to deploy your Oracle Help for the Web (OHW) helpset in the Tomcat servlet engine.

This page contains the following sections:

Installing and Running Apache Tomcat
Installing OHW and Configuring Tomcat
Testing the Installation
Setting Up the Shared UIX Installable Resource Files
Upgrading OHW and UIX

Installing and Running Apache Tomcat

Tomcat is not included in any OHW download file, so you must obtain and install it yourself. For full instructions on how to install and configure Tomcat, refer to the Tomcat documentation. However, installing Tomcat is generally quite easy:

Download Tomcat. Tomcat binaries are available from the Apache Jakarta web site at http://jakarta.apache.org/tomcat/index.html. The name of the file (at the time of this writing) is jakarta-tomcat-nnn.zip, where nnn is the release number.
Unzip the jakarta-tomcat-nnn.zip file to where you want to install Tomcat on the host computer. By default, this creates a directory structure under jakarta-tomcat-nnn.

Note: For the remainder of the instructions on this page, the name of this directory is called jakarta-tomcat.
Make sure you have the JAVA_HOME environment variable set to a directory on the host where a version of JDK 1.2 or later resides. (JDK 1.2 or later is required for Tomcat 4.0.)
To start the server, run the Tomcat startup batch file or script from the jakarta-tomcat/bin directory:
- For Windows installations type startup at a command prompt.
- For UNIX installations type ./startup.sh. If the UNIX scripts do not have executable privileges, you may need to provide these privileges using the UNIX chmod command.
Direct your browser to http://<hostname>:8080/, where <hostname> is the name of the machine on which Tomcat is installed.

A Tomcat welcome page will be displayed in your browser. If you are connected to a network, browsers on remote computers will be able to see the same content by going to the same URL.

If you are viewing Tomcat from the same computer on which it is installed, you may be able to use the URL http://localhost:8080/, depending on your browser configuration. However, anyone trying to see this from a remote computer must use the name of the host to see the content.

To stop the server, run the Tomcat shutdown batch file or script from the jakarta-tomcat/bin directory:

For Windows installations type shutdown at a command prompt.
For UNIX installations type ./shutdown.sh.

Installing OHW and Configuring Tomcat

Before following these instructions, you must install Apache Tomcat, as described above in Installing and Running Apache Tomcat.

Download the OHW deployment bundle from Oracle Technology Network at http://www.oracle.com/tech/java/help/content.html. The name of the deployment bundle file is ohw-deploy-nnn.zip, where nnn is the OHW release number. This file contains a number of Java ARchive (JAR) dependency files, the files web.xml and ohwconfig.xml, and two zip files, ohw-install.zip and uix2-install.zip.
Unzip ohw-deploy-nnn.zip to a temporary location.
Under the jakarta-tomcat/webapps/ directory in your Tomcat installation, create the following new subdirectories:
- jakarta-tomcat/webapps/ohw
- jakarta-tomcat/webapps/ohw/helpsets
- jakarta-tomcat/webapps/ohw/WEB-INF
Note: 'WEB-INF' must be all capital letters. 'ohw' is all lowercase.
To install the OHW servlet, put all the jar files from ohw-deploy-nnn.zip into the jakarta-tomcat/lib directory. The files are:
- ohw.jar
- xmlparserv2.jar
- regexp.jar
- uix2.jar
- share.jar
Unzip ohw-install.zip into the jakarta-tomcat/webapps/ohw directory. This creates a subdirectory called jsLibs and places OHW JavaScript files into the directory, such as:
```
 jakarta-tomcat/webapps/ohw/jsLibs/<files>
```
Unzip uix2-install.zip into the jakarta-tomcat/webapps/ohw directory. This creates the following cabo directory structure and places UIX installable resource files such as images, scripts, and style sheets into subdirectories:
```
 jakarta-tomcat/webapps/ohw/cabo/images/<files>
 jakarta-tomcat/webapps/ohw/cabo/jsLibs/<files>
 jakarta-tomcat/webapps/ohw/cabo/jsps/<files>
 jakarta-tomcat/webapps/ohw/cabo/styles/<files>
```
Note: To set up the UIX installable resource files for sharing among multiple web modules, see Setting Up the Shared UIX Installable Resource Files.
Place the files that make up your OHW help system in jakarta-tomcat/webapps/ohw/helpsets or, if you prefer, create subdirectories under ohw/helpsets for the files. For example, if you have two products, myProduct and otherProduct, you could create the following:
- jakarta-tomcat/webapps/ohw/helpsets/myProduct
- jakarta-tomcat/webapps/ohw/helpsets/otherProduct
Place all your help files in these directories, including the helpset file, topic (HTML) files, and the other control files (index, table of contents, etc.). For more information about these files, see Oracle Help File Formats. Also, place any JAR files here, if you are using jar files for your helpset. (You can use JARred and unJARred helpsets together in the same deployment.)
Create an ohwconfig.xml file to configure OHW. Place this file in the jakarta-tomcat/webapps/ohw/helpsets/ directory. A sample file is provided in the ohw-deploy-nnn.zip file.

Among other things, this file tells OHW where to find your helpsets and help topic HTML files. 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. The <contentLocation> element is used to specify the root location of a set of Oracle Help help topic HTML files. For more information about the owhconfig.xml file, see OHW Configuration File.

Sample edit:
```
 <books combineBooks="false" useLabelInfo="true">
    <helpSet location="myProduct/myProduct.hs" />
    <helpSet jar="otherProduct/otherProduct.jar" location="otherProduct.hs" />
 </books>
```
Create the web.xml file in the jakarta-tomcat/webapps/ohw/WEB-INF directory. A sample web.xml file is provided in the ohw-deploy-nnn.zip file. You must edit this file before you can use it with Tomcat. Open web.xml in a text editor and remove the three lines that read:
```
 <login-config>
    <auth-method>BASIC</auth-method>
 </login-config>
```
Your final web.xml should be similar to the following sample XML file, which can be used as long as the ohwconfig.xml file is in the jakarta-tomcat/webapps/ohw/helpsets/ directory.

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>:8080/ohw/onlinereference/.

The following parameter specifies the location of the OHW configuration file (ohwconfig.xml):
```
 <init-param>
   <param-name>configFileName</param-name>
   <param-value>/helpsets/ohwconfig.xml</param-value>
 </init-param>
```
The path of the configuration file is specified relative to location of the servlet context path. For most users we recommend that you do not modify this parameter.

Testing the Installation

To see your help in OHW, do the following:

Start Tomcat by running startup.bat or startup.sh, as described in Step 4 of Installing and Running Apache Tomcat, above.
Direct your browser to http://<hostname>:8080/ohw/help/

Note: The last slash ('/') is required.

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

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.

Setting Up the Shared UIX Installable Resource Files

To enable multiple applications to share a single set of UIX installable resource files, install the UIX resource files in the webapps/ROOT directory of the Tomcat installation.

Unzip uix2-install.zip into the jakarta-tomcat/webapps/ROOT directory. This creates the cabo subdirectory and places UIX installable resource files such as images, scripts, and style sheets into subdirectories.
Create the jakarta-tomcat/webapps/ROOT/cabo/WEB-INF directory and copy the following contents into the web.xml file.

Sample web.xml file for UIX resource files:
```
 <?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.

Modify the Tomcat Catalina batch file or script in the jakarta-tomcat/bin directory to specify the location of the UIX installable resource files via the system property oracle.cabo.ui.sharedContextPath.

Sample edit:

%_EXECJAVA% %JAVA_OPTS% %CATALINA_OPTS% %DEBUG_OPTS% -
Doracle.cabo.ui.sharedContextPath=\jakarta-tomcat\webapps\ROOT -
Djava.endorsed.dirs="%JAVA_ENDORSED_DIRS%" -classpath "%CLASSPATH%" -
Dcatalina.base="%CATALINA_BASE%" -Dcatalina.home="%CATALINA_HOME%" -
Djava.io.tmpdir="%CATALINA_TMPDIR%" %MAINCLASS% %CMD_LINE_ARGS% %ACTION%

Remove all private copies of the UIX installable resource files in the web applications, e.g., jakarta-tomcat/webapps/ohw/cabo.

Upgrading OHW and UIX

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

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

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

Repeat Step 4 in Installing OHW and Configuring Tomcat, above. This updates the OHW and UIX JAR files.
Repeat Step 5 in Installing OHW and Configuring Tomcat, above. This unzips files from ohw-install.zip and updates the OHW JavaScript files in the jakarta-tomcat/webapps/ohw/jsLibs directory.

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 Tomcat server installation is using shared UIX installable resource files, repeat Step 1 in Setting Up the Shared UIX Installable Resource Files, above. This unzips files from uix2-install.zip into the jakarta-tomcat/webapps/ROOT directory, updating the cabo directory and its subdirectories.

Note: Remember to delete the runtime cache directory, jakarta-tomcat/webapps/ohw/cabo.
If each web application has a private copy of the UIX installable resource files, repeat Step 6 in Installing OHW and Configuring Tomcat, above. This unzips files from uix2-install.zip into the jakarta-tomcat/webapps/ohw directory, updating the cabo directory and its subdirectories.