Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Help
11g Release 2 (11.1.2.0.0)

Part Number E16280-01
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

17 Understanding OHW Deployment

Once help authors have finished creating the help contents, then OHW administrator must modify the Web configuration to deploy those help contents using OHW.

You can deploy OHW in multiple ways. However, there are certain tasks that are common to all deployment modes. This chapter describes those common tasks that are a prerequisite for further steps.

If you are new to OHW, you may start with deploying the demo file. For more information, see Chapter 16, "Deploying OHW Demo File". The demo EAR file includes all files needed to deploy the sample helpsets immediately.

If you are creating a new OHW helpset, the following sections help you understand the OHW deployment process and describe the steps required to create and deploy your own OHW help system.

Unless configuration files have already been created and the application server configured, the OHW administrator must perform these tasks to deploy an OHW help system:

17.1 Verifying Requirements and Dependencies

The following requirements must be verified for OHW:

Table 17-1 OHW Deployment Minimum Requirements

Requirement Description

Application Server

The OHW requires a Java EE 1.5 compatible application server that could support Java Servlet, JSP and JSF. Oracle WebLogic Server, standalone or integrated with JDeveloper, is recommended as it requires minimal configuration effort. For more information abot supported application servers, see Application Servers section in "Certification Information" on OTN.

Client

The client receives only HTML, and all it requires is a web browser to display and view the OHW help content. The web browser must have JavaScript support enabled.

OHW is supported in Microsoft Internet Explorer 7, Microsoft Internet Explorer 8, Mozilla FireFox 2, Mozilla FireFox 3, Apple Safari, and Google Chrome. For more information about supported browsers, see the ADF Faces and Data Visualizations section in "Release Notes - JDeveloper 11g" on OTN.

Rich ADF Faces

OHW needs Rich ADF Faces libraries and their dependencies to be available. The application server should also be configured for ADF-based applications by installing the correct JAR files or by running the ADF Runtime Installer using Oracle JDeveloper. For more information, see the online help of Oracle WebLogic Application Console.


17.2 Verifying OHW Library Files

The application server where you deploy the OHW help files, must be configured to support Rich ADF Faces, because OHW depends on that technology.

If you are using Oracle WebLogic Server, review your Oracle WebLogic Application Console and confirm that following libraries are also deployed:

The libraries are listed on Deployment page of Oracle WebLogic Application Console. If the libraries are not installed, extend your WebLogic domain using Oracle WebLogic Configuration Wizard to include Oracle JRF libraries. After including Oracle JRF libraries, restart your Oracle WebLogic Server and the libraries would be listed in Deployments page of Oracle WebLogic Application Console. For more information about extending a domain, see Oracle Fusion Middleware Administrator's Guide.

If you are not using Oracle WebLogic Server, ensure that all ADF, JSF and JSTL library JAR files are copied in \WEB-INF\lib directory of WAR deployment file. You can download the library files from OTN, or copy them from the demo file. The libraries are available in ohw-rcf-demo-thick\ohw-rcf-demo-thick\WEB-INF\lib directory of ohw-rcf-demo-thick.ear file.

17.3 Installing OHW Artifacts

There are some files needed to be installed on the server to make OHW working. The details about this will be shown in different possible deployment of OHW topics.

The OHW distributable components consist of JAR files like ohw-rcf.jar, ohw-share.jar, help-share.jar, and ohw-rcf-webapp.zip. The ohw-rcf-webapp.zip contains the helppages directory, which contains installable files like jspx (XML style of a JSF page) that are needed to run OHW properly.

All artifacts are available on OTN for download.

17.4 Understanding OHW Configuration Files

Before you start deploying the OHW helpset, there are some files that must be created or modified to configure OHW correctly. The following information helps you understand the XML configuration files:

17.5 Configuring OHW to Display Custom Helpsets

The instructions in this section helps you create the directory structure required for OHW help system, add your custom helpset files in the correct location, create or modify the configuration files, and deploy the help system on application server.

The instructions in this section also assume that you have installed the OHW demo EAR file and you have a knowledge of the demo EAR file's directory structure. If you have not installed the demo file, install it following instructions in Chapter 16, "Deploying OHW Demo File".

Follow these steps to set up your OHW help system:

  1. Set up the directory structure as following:

    <OHW-RC_HOME>
      |
      — <OHW-RC_deployment_name>
          |
          — helppages
          — helpsets
              |
              — <custom_helpset_directory>
          — META-INF
          — WEB-INF
              |
              — lib
      — META-INF
    

    For example:

    my_module
      |
      — my_module_help
          |
          — helppages
          — helpsets
              |
              — my_ModuleHelpset
          — META-INF
          — WEB-INF
              |
              — lib
      — META-INF
    
  2. Create your own helpset directory. Place all your help files in or under <OHW_HOME>\<OHW_deployment_name>\helpsets\<custom_helpset_directory> directory, including the helpset file, topic files, and the other control files (index, table of contents, and so on). 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.

  3. Update and configure the configuration file. Copy the demo EAR's ohwconfig.xml from ohw-rc-thick-demo\ohw-rc-thick-demo\helpsets directory and save it in your <OHW_HOME>\<OHW_deployment_name>\helpsets directory. Edit the file according to your requirement:

    1. Modify the <books></books> section to direct it to your helpset. For example:

      <books>
        <helpSet id="myModule" location="my_ModuleHelpset/my_ModuleHelpset.hs" />
      </books>
      
    2. Remove the helpsets which you do not want to provide from the <books></books> section. If removed, the helpsets would not appear in the helpset switcher dropdown list of the OHW user interface. If you have only one <helpSet> element in the <books></books> section, the helpset switcher is not available.

    3. Update the <brandings></brandings> section to display your own brand. For example:

      <brandings>
        <branding text="My Module" />
      </brandings>
      

    For more information about ohwconfig.xml file behaviors you can configure, see Chapter 8, "Oracle Help for the Web Configuration File".

  4. Copy the ohw-rc-thick-demo\ohw-rc-thick-demo\helppages directory to your <OHW_HOME>\<OHW_deployment_name> directory.

  5. Copy the following library files from JDeveloper to <OHW_HOME>\<OHW_deployment_name>\WEB-INF\lib directory.

    File Name Location
    JSF library file (jsf-1.2.war) <JDEV_HOME>\wlserver_10.3\common\deployable-libraries
    JSTL library file (jstl-1.2.war) <JDEV_HOME>\wlserver_10.3\common\deployable-libraries
    ADF library files (adf-richclient-api-11.jar, adf-richclient-impl-11.jar) <JDEV_HOME>\oracle_common\modules\oracle.adf.view_11.1.1

  6. Configure faces-config.xml and trinidad-config.xmlto configure JSF and JSTL support in OHW. Copy the XML files from ohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INF directory and save them in in <OHW_HOME>\<OHW_deployment_name>\WEB-INF directory.

    The faces-config.xml is the JSF configuration file where you register a JSF application's resources and define the page-to-page navigation rules. The trinidad-config.xml enables you to configure ADF Faces features. Like faces-config.xml, the trinidad-config.xml file has a simple XML structure that enables you to define element properties using the JSF Expression Language (EL) or static values.

  7. If you are using Oracle WebLogic Server, copy the weblogic.xml from ohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INF directory and save it in your <OHW_HOME>\<OHW_deployment_name>\WEB-INF directory. Then, edit the file to your requirements.

  8. Copy the web.xml from ohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INF directory and save it in <OHW_HOME>\<OHW_deployment_name>\WEB-INF directory. Then, edit it to your requirements:

    1. Modify the <display-name></<display-name> and <description></description> section to display your custom helpset name. For example:

      <web-app>
        <display-name>My Module</display-name>
        <description>My module help</description>
      </web-app>
      
    2. Optionally, you may want to edit the <servlet-name> element under <servlet> element to change your URL used to access OHW. For more information about changing the access URL, see Section 17.6, "Changing the OHW-RC Access URL" .

  9. Compress the <OHW-RC_deployment_name> directory into a WAR file.

  10. Copy the application.xml from ohw-rc-thick-demo\META-INF directory and save it in <OHW-RC_HOME>\META-INF directory. Then, edit the file to your requirements. In this file, provide the web module name of each product that you want to deploy.

    You may also Specify the WAR file name, created in step 9, in <web-uri></web-uri> element. If you want to change the access URL of the application, update the <context-root><context-root> element. For more information, see Section 17.6.2, "Changing the access URL to another name".

  11. Compress the <OHW_HOME> directory into a EAR file.

  12. Start the Oracle WebLogic Server and deploy the EAR file. If Oracle WebLogic Server is running, you must shut it down and then restart it before the changes made since you last started the servlet are available. For more information about deploying an EAR file, see the "Install an Enterprise application" section in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

  13. Direct the browser to http://<hostname>:<port>/<OHW-RC_deployment_name>/ohguide/, where <hostname> is the name of the system on which Oracle WebLogic Server is installed.

    The first page of the demo help system displays in the browser. If there are multiple helpsets, use the dropdown list in the toolbar to select a helpset, then click the helpset switcher to display the TOC and index from the selected helpset only. The text search searches only for items in the selected helpset.

17.6 Changing the OHW-RC Access URL

The URL to access OHW is http://<hostname>:<port>/mymodule/ohguide/, where <hostname> is the name of the system on which OHW and Oracle WebLogic Server are installed.

You can change this URL in the following ways:

17.6.1 Changing the final URL element of the access URL

To change the help at the end of the URL, edit web.xml in <OHW_HOME>\<OHW_deployment_name>\WEB-INF.

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>:<port>/mymodule/onlinereference/.

For example:

<servlet-mapping>
   <servlet-name>mymodule</servlet-name>
   <url-pattern>/onlinereference/*</url-pattern>
</servlet-mapping>

17.6.2 Changing the access URL to another name

To change the access URL for your application , edit the <context-root> element entry under <web> element in application.xml, located in <OHW_HOME>\META-INF:

<web>
   <web-uri>my_module.war</web-uri>
   <context-root>my_module</context-root>
</web>

For example, if you want the OHW access URL to be http://<hostname>:<port>/jdeveloper/help/, modify the root element:

<web>
   <web-uri>my_module.war</web-uri>
   <context-root>jdeveloper</context-root>
</web>

17.7 Deploying OHW as a Standalone Web Application

One of the ways that OHW can be deployed is to have it as a standalone Web application. To deploy OHW as a standalone application, an OHW WAR file, containing all files needed to run the OHW, must be copied into a separate deployment directory in the application server that has a dedicated context path.

The OHW administrator must perform some primary tasks, and then go on to deploy the OHW help system as a standalone Web application, as follows. To know more about the tasks, see Chapter 17, "Understanding OHW Deployment".

17.7.1 Installing the OHW-RC Artifacts

The Oracle WebLogic Server and other servlet containers allow OHW modules to be compressed as WAR (Web ARchive) files, which are then deployed as an EAR (Enterprise ARchive) file, which wraps any WAR and JAR (Java ARchive) files and the OHW installable files. One way to do this is to create WAR or EAR files using the standard Java JAR utility.

Then the OHW WAR or EAR file must be extracted by the application server so that the Web client can access the OHW pages. You may consult the relevant application server guidelines on how to deploy WAR or EAR files.

Another way is to manually create the Web application using a web developer studio like Oracle JDeveloper Studio, include the ohw-rcf.jar, ohw-share.jar, help-share.jar in the library path, and extract the ohw-rcf-webapp.zip to the public html directory.

17.7.2 Configuring OHW as Standalone Web Application

After all files have been put in the right locations, the OHW administrator still must modify some configuration files to make OHW work:

  • Modify web.xml file to include JSF and Trinidad parameters.

    For example:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
      <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>client</param-value>
      </context-param>
      <context-param>
        <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
        <param-value>false</param-value>
      </context-param>
      ...
      ...
    </web-app>
    
  • Modify web.xml to support OHW front servlets and JSF filter.

    For example:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
      ...
      ...
      <filter>
        <filter-name>trinidad</filter-name>
        <filter-class>
            org.apache.myfaces.trinidad.webapp.TrinidadFilter
        </filter-class>
      </filter>
      <filter-mapping>
        <filter-name>trinidad</filter-name>
        <servlet-name>Faces Servlet</servlet-name>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>REQUEST</dispatcher>
      </filter-mapping>
      <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
      </servlet>
      <servlet>
        <servlet-name>OHW Servlet 1</servlet-name>
        <servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
        <init-param>
          <param-name>ohwConfigFileURL</param-name>
          <param-value>/helpsets/ohwconfig.xml</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
      </servlet>
      <servlet-mapping>
        <servlet-name>OHW Servlet 1</servlet-name>
        <url-pattern>/ohguide/*</url-pattern>
      </servlet-mapping> 
      ...
      ...
    </web-app>
    
  • If you have not created ohwconfig.xml and helpsets directory, create the file and directory as described in steps 1, 2, and 3 of Section 17.5, "Configuring OHW to Display Custom Helpsets".

    If created, modify ohwconfig.xml, and edit the help content as required. It specifies which helpsets to display and how to present them. You can also specify locales, branding information, and various other settings. The name and location of this file is set as the ohwConfigFileURL servlet initialization parameter, which is handled differently for each servlet container. The ohwConfigFileURL parameter is defined in web.xml to specify param-value.

    For information about this configuration file, see Chapter 8, "Oracle Help for the Web Configuration File".

If you want to provide the help content outside of the applcation's EAR file, you must configure the web.xml file. In the <param-value> element, you can use a variable to define the path of ohwconfig.xml using the following syntax:

<init-param>
  <param-name>ohwConfigFileURL</param-name>
  <param-value>
    file:///{%yourVariableName}/help/ohwconfig.xml
  </param-value>
</init-param>

When OHW finds a variable (for example, {%yourVariableName}) in the path, it looks for the Java system property of the same name (yourVariableName), and then replaces the value of the variable with the value defined in Java system property. You can define Java system property in your Oracle WebLogic Server startup scripts.

Support for Ctrl+N Shortcut to Open a New Help Window

You can configure web.xml to open a new browser window when a users Ctrl+N shortcut. Add the following code in web.xml to enable the shortcut support:

<context-param>
  <param-name>oracle.adf.view.rich.newWindowDetect.OPTIONS</param-name>
  <param-value>on</param-value>
</context-param>

Support for Partial Page Navigation

To improve performance, you can enable partial page navigation support in OHW. By default, the support is disabled in ADF Faces application, but you can enable it in your helpset by adding the following code in web.xml:

<context-param>
  <param-name>oracle.adf.view.rich.pprNavigation.OPTIONS</param-name>
  <param-value>onWithForcePPR</param-value>
</context-param>

17.8 Deploying OHW as part of a Web Application

One way to deploy the OHW is to make it co-exist with your Web application. The Web application could be a JSF, ADF, or JSP application or any Java EE Web application. OHW then could be deployed as one of the Web projects within the existing application.

When you deploy OHW as part of an existing web application, the web application and OHW help system, both, share the same web.xml. This could limit the fine tuning of OHW help system and may cause conflict with your application. It is recommended that you deploy OHW separately from your web application, and then link the help system with your application. For more information, see Section 17.7, "Deploying OHW as a Standalone Web Application". If your application is using ADF Faces, you may use helpTopicId attribute on the ADF Faces components for an ADF application. For more information, see Section 19.1, "Integrating Online Help With ADF Faces Application".

17.8.1 Installing the OHW Artifacts

Extract the ohw-rcf-webapp.zip to the public_html folder (or the web application root directory) of the existing Web application.

Copy the ohw-rcf.jar, ohw-share.jar, help-share.jar files to the application's WEB-INF/lib folder, or to the defined library folder. If you are developing in JDeveloper, remember to add these jars to your project (Project Properties > Libraries and Classpath).

17.8.2 Configuring OHW as Part of Web Application

After all files have been put in the right locations, the OHW administrator must modify some configuration files to make OHW work:

  • Modify web.xml file to include JSF and Trinidad parameters if it does not exist.

    For example:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
      <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>client</param-value>
      </context-param>
      <context-param>
        <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
        <param-value>true</param-value>
      </context-param>
      ...
      ...
    </web-app>
    
  • Modify web.xml to support OHW front servlets and JSF filter.

    Since the OHW is part of existing application, the OHW administrator must ensure that the load-on-startup ordering is maintained in the right sequence.

    For example:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
      ...
      ...
      <filter>
        <filter-name>trinidad</filter-name>
        <filter-class>
            org.apache.myfaces.trinidad.webapp.TrinidadFilter
        </filter-class>
      </filter>
      <filter-mapping>
        <filter-name>trinidad</filter-name>
        <servlet-name>Faces Servlet</servlet-name>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>REQUEST</dispatcher>
      </filter-mapping>
      <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
      </servlet>
      <servlet>
        <servlet-name>product1</servlet-name>
        <servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
        <init-param>
          <param-name>ohwConfigFileURL</param-name>
          <param-value>/helpsets/product1/ohwconfig.xml</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
      </servlet>
      ...
      ...
    </web-app>
    
  • Modify ohwconfig.xml, and edit the help content as needed. If you have not created helpsets or ohwconfig.xml file, create them as described in steps 1, 2, and 3.

    The ohwconfig.xml file specifies which helpsets to display and how to present them. You can also specify locales, branding information, and various other settings. The name and location of this file is set as the ohwConfigFileURL servlet initialization parameter (defined in web.xml), which is handled differently for each servlet container. For information about this configuration file, see Chapter 8, "Oracle Help for the Web Configuration File".

17.9 Deploying Multiple Help Instances in a Web Application

OHW supports the deployment of multiple help instances (a single help instance may contain multiple helpsets) in a single Web application or enterprise application. One of the main reasons for providing this support is to minimize the changes needed when upgrading from a OHW configuration. The deployment of multiple help instances for OHW is achieved by providing an OHW front servlet that forwards the request to the JSF servlet.

17.9.1 Application and OHW Configuration Files and Setup

You must modify the web.xml file of your application to add servlet mapping to the OHW front servlets.

Here is an example of the changes that must be done to the web.xml file, to support the deployment of multiple help instances for OHW:

<!-- configuration for product1 help front servlet -->
<servlet>
  <servlet-name>product1</servlet-name>
  <servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
  <init-param>
    <param-name>ohwConfigFileURL</param-name>
    <param-value>/helpsets/product1/ohwconfig.xml</param-value>
  </init-param>
  <load-on-startup>2</load-on-startup>
</servlet>
 
<!-- configuration for product2 help front servlet -->
<servlet>
  <servlet-name>product2</servlet-name>
  <servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
  <init-param>
    <param-name>ohwConfigFileURL</param-name>
    <param-value>/helpsets/product2/ohwconfig.xml</param-value>
  </init-param>
  <load-on-startup>3</load-on-startup>
</servlet>
 
<servlet-mapping>
  <servlet-name>product1</servlet-name>
  <url-pattern>/product1/*</url-pattern>
</servlet-mapping>
 
<servlet-mapping>
  <servlet-name>product2</servlet-name>
  <url-pattern>/product2/*</url-pattern>
</servlet-mapping>

In the above sample code, there are two OHW front servlets called product1 and product2. Each servlet can load a different OHW configuration file that determines the set of books and views shown in the user interface. The product1 servlet is mapped to URL pattern of /product1/*. So, if you specified a URL mapped to the rich OHW context root that has product1 at the end portion of the URL, it is re-routed to this servlet. Similarly, the product2 is mapped to the URL pattern of /product2/*.

17.9.2 Running the application

Once you have successfully deployed OHW in the application server, you can connect to any OHW front servlet you have configured, using a URL similar to the following:

http://www.myhelpserver.com:<port>/docs/product1

The above URL calls the servlet product1 that loads the OHW configuration file from /helpsets/product1/ohwconfig.xml and is redirected to a URL like this:

http://www.myhelpserver.com:<port>/docs/faces/helppages/main.jspx?config=product1

OHW can also process locale and group information appended to the URL (similar to OHW).