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

Deploying OHW on OC4J Using the Demo Bundle

One of the Oracle Help for the Web (OHW) release files available for downloading from the Oracle Technology Network (OTN) includes a preconfigured version of OHW installed in the Oracle Application Server Containers for J2EE (OC4J) Java servlet engine. OC4J is a development environment for Java 2 Enterprise Edition (J2EE), and it includes a servlet engine that supports the Java Servlet 2.2 and 2.3 specification.

The OHW demo bundle contains all the debug class libraries that you need to view the demo and try out the release. It includes a preconfigured Oracle OC4J 9.0.x servlet engine, sample helpsets plus batch and script files for starting and stopping the OC4J servlet engine and the OHW servlet. You can install and run this version without modification, just to see how OHW works, or you can replace the sample helpsets with your own.

This page contains the following sections:

Installing and Running the OHW Demo Bundle
Understanding the OHW Demo Bundle Files
Configuring OHW on OC4J to Display User Helpsets
Adding a Web Module
Changing the OHW Access URL

Installing and Running the OHW Demo Bundle

For the latest information, check any download and install instructions that may be available on the OHW download page. However, installing the demo bundle is generally quite simple:

Download the OHW demo bundle from OTN at http://www.oracle.com/technology/tech/java/help/. The name of the demo bundle file is ohw-demo-nnn.zip, where nnn is the OHW release number. For example, ohw-demo-1_1_1.zip. This file includes OHW, sample helpsets, and the OC4J servlet engine.
Unzip ohw-demo-nnn.zip in the location you wish to install the demo on the host computer.

This unzips files into the ohw directory. For details about the demo bundle files, see Understanding the OHW Demo Bundle Files.
Make sure you have the JAVA_HOME environment variable set to a directory on the host computer where a version of JDK 1.2.2 or later resides (JDK 1.3.1 is recommended).
To start the server, run the OHW/OC4J startup batch file or script from the ohw/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.
You should see some output that indicates OC4J has started, such as "Oracle Application Server <version> Containers for J2EE initialized."
To view the OHW demo, direct your browser to http://<hostname>:8888/ohw/help/, where <hostname> is the name of the host machine on which OHW and OC4J are installed.

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

OHW will be displayed in your browser, showing the first page of the help system (usually a table of contents). 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 OHW from the same computer on which it is installed, you may be able to use the URL http://localhost:8888/ohw/help/, depending on your browser configuration. However, anyone trying to see this help from a remote computer must use the name of the host to see the content.

To stop the server, run the OHW/OC4J shutdown batch file or script from the ohw/bin directory:

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

Understanding the OHW Demo Bundle Files

OC4J is capable of handling multiple J2EE applications, each of which consists of one or more application modules. Application modules can be: 1) a web module that runs under the control of a servlet that may employ JSPs as well, 2) an EJB application, or 3) a Java client application module. OHW application modules are web modules.

The OHW demo bundle unzips files into the ohw directory. It creates the ohw/oc4j/j2ee/home directory, which contains all the files necessary for running OC4J with a default configuration.

The OC4J configuration used in the OHW demo bundle consists of two J2EE applications, one for OHW and one for UIX. The OHW application (ohw-eapp) provides one web module for each product and its single helpset or multiple helpsets. The UIX application (uixresources-eapp) enables multiple web modules to share a single set of UIX installable resource files.

The OHW and UIX JAR files are installed in the directory ohw/oc4j/j2ee/home/lib. OHW JavaScript files are installed in ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/jsLibs. Each web module must have a private copy of the OHW JavaScript files.

One web module containing two helpsets is provided in the demo bundle. The demo helpset files are installed in ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/helpsets. Two helpset subdirectories are included: fileformats and shakespeare.

The UIX installable resource files are installed in the ohw/oc4j/j2ee/home/applications/uixresources-eapp/cabo directory and its subdirectories. During runtime, the ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/cabo directory is automatically created. (For instructions on how to create the UIX Resources application, see Deploying OHW on OC4J Using the Deploy Bundle.

Note: In OHW releases prior to 1.0.8 and 1.1.x, the OHW demo bundle was not configured for shared UIX installable resources. Each web module had a private copy of the UIX resource files.

The OC4J configuration files that are of interest with respect to OHW deployment are:

  ohw/oc4j/j2ee/home/config/server.xml
  ohw/oc4j/j2ee/home/config/http-web-site.xml
  ohw/oc4j/j2ee/home/applications/ohw-eapp/META-INF/application.xml
  ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/WEB-INF/web.xml
  ohw/oc4j/j2ee/home/applications/uixresources-eapp/META-INF/application.xml
  ohw/oc4j/j2ee/home/applications/uixresources-eapp/cabo/WEB-INF/web.xml

The only OHW configuration file, ohwconfig.xml, is located in ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/helpsets.

Configuring OHW on OC4J to Display User Helpsets

The instructions in this section assume you have installed the OHW demo bundle. If you have not installed the demo, see Installing and Running the OHW Demo Bundle.

While the OHW demo bundle includes sample helpsets, you will probably want to use OHW to display your own helpsets. You can easily substitute your own helpsets for the demo helpsets by copying them into the ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/helpsets directory, and then modifying the ohwconfig.xml file. To do so, follow these steps:

Install the control and content files for your help system. Ordinarily--and for convenience--helpsets are installed in or under the OHW helpsets directory. (The directory structure ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/helpsets is installed by default wherever you installed the OHW demo bundle.) For example, for a product called myProduct, you might create a directory such as:
```
 ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/helpsets/myProduct
```
Place all your help files in or under this directory, 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.)
Edit the configuration file. In an editor, open the ohwconfig.xml file, which is by default in the ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/helpsets directory. Modify the <books></books> section to direct it to your helpset. For example:
```
 <books combineBooks="true" useLabelInfo="true">
  <helpSet location="myProduct/myProductHelp.hs" />
  <helpSet jar="otherProduct/otherProduct.jar" location="otherProduct.hs" />
 </books>
```
Among other things, the ohwconfig.xml 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 ohwconfig.xml file, see OHW Configuration File.
Start the servlet engine. Start the servlet engine, as described in Step 4 of the section Installing and Running the OHW Demo Bundle, above . 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 the browser to http://<hostname>:8888/ohw/help/, where <hostname> is the name of the machine on which OHW and OC4J are installed.

The first page of the demo 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.

Adding a Web Module

The instructions in this section assume you have installed the OHW demo bundle. If you have not installed the demo, see Installing and Running the OHW Demo Bundle.

While the OHW demo bundle includes a sample web module (ohw), you will probably want to create your own web module to display other helpsets. You can easily do this by copying files from the directory ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw, and then modifying the files ohwconfig.xml, application.xml, and web.xml. To do so, follow these steps:

Create a web module directory. Create the new directory under ohw/oc4j/j2ee/home/applications/ohw-eapp. For example, you might create the directory for a new web module called mymodule as:
```
 ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule
```
Copy the web.xml file and OHW Javascript files. Each web module must have a web.xml file and a private copy of the OHW JavaSCript files. Copy the directories ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/jsLibs and ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/WEB-INF and place them in ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule. You should now have the following structure for your new web module:
```
 ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule/jsLibs/<files>
 ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule/WEB-INF/web.xml
```
Install the control and content files for your help system. Create the helpsets directory in your web module directory and install your help files in or under the helpsets directory. For example, for a product called myProduct, you might create a directory such as:
```
 ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule/helpsets/myProduct
```
Place all your help files in or under this directory, 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.)
Edit the configuration file. Copy ohwconfig.xml from ohw/oc4j/j2ee/home/applications/ohw-eapp/ohw/helpsets and place it in ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule/helpsets.

In an editor, open the ohwconfig.xml file in ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule/helpsets and modify the <books></books> section to direct it to your helpset. For example:
```
 <books combineBooks="true" useLabelInfo="true">
  <helpSet location="myProduct/myProductHelp.hs" />
  <helpSet jar="otherProduct/otherProduct.jar" location="otherProduct.hs" />
 </books>
```
Among other things, the ohwconfig.xml 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 ohwconfig.xml file, see OHW Configuration File.

Add the new web module information to the application.xml file. In an editor, open the file ohw/oc4j/j2ee/home/applications/ohw-eapp/META-INF/application.xml and add the following lines within the <application></application> section:

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

Your final application.xml file should be similar to the following sample XML file.

Sample application.xml file:

 <?xml version="1.0"?>
 <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
 "http://java.sun.com/aplication_1_3.dtd">
  
 <application>
 
   <display-name>ohw-eapp</display-name>
   <module>
     <web>
       <web-uri>ohw</web-uri>
       <context-root>/</context-root>
     </web>
   </module>

   <module>
     <web>
       <web-uri>mymodule</web-uri>
       <context-root>/</context-root>
     </web>
   </module>
    
 </application>

Bind the new web module access location to the OHW application. In an editor, open the file ohw/oc4j/j2ee/home/config/http-web-site.xml and add the following line:

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

Your final http-web-site.xml file should be similar to the following sample XML file.

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="ohw" root="/ohw" />
   <web-app application="ohw-eapp" name="mymodule" root="/mymodule" />
   <web-app application="uixresources-eapp" name="cabo" root="/cabo" />
   <access-log path="../log/http-web-access.log" />
 </web-site>

Note: name="mymodule" and the <web-uri></web-uri> name in Step 5 above should use the same name.

Start the servlet engine, as described in Step 4 of the section Installing and Running the OHW Demo Bundle, above . 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.
To view the help system, direct the browser to http://<hostname>:8888/mymodule/help/, where <hostname> is the name of the machine on which OHW and OC4J are installed.
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.

Changing the OHW Access URL

As seen in the section Adding a Web Module above, the URL to access OHW is http://<hostname>:8888/mymodule/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 "mymodule" name to another name

Changing the "help" at the end of the URL

Edit the web.xml file to change the "help" at the end of the URL. The web.xml file in Step 2 of the section Adding a Web Module should be similar to the following sample XML file, which can be used as long as the ohwconfig.xml file is in the ohw/oc4j/j2ee/home/applications/ohw-eapp/mymodule/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 become http://<hostname>:8888/mymodule/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.

Changing "mymodule" to another name

Edit the http-web-site.xml file to change the "mymodule" name to another name.

Step 6 of the section Adding a Web Module above, shows a sample http-web-site.xml file.

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

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