Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Help
11g Release 1 (5.1)
E14149-02
  Go To Table Of Contents
Contents		 Go To Index
Index
Previous
Previous 		 Next
Next		  

18 Understanding OHW-RC Deployment

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

You can deploy OHW-RC in more than one way. 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-RC, you may start with deploying the demo file. For more information, see Chapter 17, "Deploying OHW-RC Demo File". The demo EAR file includes all files needed to deploy the sample helpsets immediately.

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

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

18.1 Verifying Requirements and Dependencies

The following requirements must be verified for OHW-RC:

Table 18-1 OHW-RC Deployment Minimum Requirements

Requirement Description

Application Server

The OHW-RC 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-RC help content. The web browser must have JavaScript support enabled.

OHW-RC 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-RC 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.

18.2 Verifying OHW-RC Library Files

The application server where you will deploy the OHW-RC help files, needs to be configured to support Rich ADF Faces, because OHW-RC 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 you will notice the libraries 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.

18.3 Installing OHW-RC Artifacts

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

The OHW-RC 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-RC properly.

All artifacts are available on OTN for download.

18.4 Understanding OHW-RC Configuration Files

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

18.5 Configuring OHW-RC to Display Custom Helpsets

The instructions in this section will help you create the directory structure required for OHW-RC 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-RC 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 17, "Deploying OHW-RC Demo File".

Follow these steps to set up your OHW-RC 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-RC_HOME>\<OHW-RC_deployment_name>\helpsets\<custom_helpset_directory> directory, including the helpset file, topic files, and the other control files (index, table of contents, etc.). 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. Create the configuration file. In an editor, create an XML file and save it as ohwconfig.xml, in the <OHW-RC_HOME>\<OHW-RC_deployment_name>\helpsets directory. You may also copy the ohwconfig.xml from demo EAR file and edit it to your requirement. The file is available in ohw-rc-thick-demo\ohw-rc-thick-demo\helpsets directory.

    If you are creating a new ohwconfig.xml file, see Chapter 9, "Oracle Help for the Web Configuration File" for more information about behaviors you can configure.

    If you are editing the demo EAR file's ohwconfig.xml, follow these instructions:

    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 wish to provide from the <books></books> section. If removed, the helpsets would not appear in the helpset switcher dropdown list of the OHW-RC 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>

  4. Download the ohw-rc-5_0.zip from OTN. Extract the contents of the zip file in a temporary directory, and then extract the contents of ohw-rcf-webapp.zip to <OHW-RC_HOME>\<OHW-RC_deployment_name>\helppages directory.

    You may also copy the helppages directory from the demo EAR file. The files are available in ohw-rc-thick-demo\ohw-rc-thick-demo\helppages directory.

  5. Copy the following library files to <OHW-RC_HOME>\<OHW-RC_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. Create the XML configuration files, faces-config.xml and trinidad-config.xml, to configure JSF and JSTL support in OHW-RC. The files must be located in <OHW-RC_HOME>\<OHW-RC_deployment_name>\WEB-INF directory.

    You may also copy the XML files from the demo EAR file and edit them. The files are available in ohw-rc-thick-demo\ohw-rc-thick-demo\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 allows 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, create the weblogic.xml deployment descriptor file in <OHW-RC_HOME>\<OHW-RC_deployment_name>\WEB-INF directory.

    You may also copy the weblogic.xml from demo EAR file and edit it to your requirements. The file is available in ohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INF directory.

  8. Create web.xml to set the initialization parameters in <OHW-RC_HOME>\<OHW-RC_deployment_name>\WEB-INF directory.

    You may also copy the web.xml from demo EAR file and edit it to your requirements. The file is available in ohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INF directory.

    If you are editing the demo EAR file's web.xml, follow these instructions:

    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 wish to edit the <servlet-name> element under <servlet> element to change your URL used to access OHW-RC. For more information about changing the access URL, see Section 18.6, "Changing the OHW-RC Access URL" .

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

  10. Create application.xml in <OHW-RC_HOME>\META-INF directory. In this file, you will provide the web module name of each product that you will deploy.

    You may also copy the application.xml from demo EAR file and edit it to your requirements. The file is available in ohw-rc-thick-demo\META-INF directory. Specify the WAR file name, created in step 9, in <web-uri></web-uri> element. If you wish to change the access URL of the application, update the <context-root><context-root> element. For more information, see Section 18.6.2, "Changing the access URL to another name".

  11. Compress the <OHW-RC_HOME> directory into a EAR file.

  12. Start the Oracle WebLogic Server and deploy the EAR file. If Oracle WebLogic Server is already running, you must shut it down and then restart it before the changes made since you last started the servlet will be 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 machine on which Oracle WebLogic Server is installed.

    The first page of the demo help system displays in the browser. If there is more than one helpset, 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 will search only for items in the selected helpset.

18.6 Changing the OHW-RC Access URL

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

You can change this URL in the following ways:

18.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-RC_HOME>\<OHW-RC_deployment_name>\WEB-INF.

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

For example:

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

18.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-RC_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-RC 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>

18.7 Deploying OHW-RC as a Standalone Web Application

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

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

18.7.1 Installing the OHW-RC Artifacts

The Oracle WebLogic Server and other servlet containers allow OHW-RC 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-RC installable files. One way to do this is to create WAR or EAR files using the standard Java JAR utility.

Then the OHW-RC WAR or EAR file needs to be extracted by the application server so that the Web client can access the OHW-RC 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.

18.7.2 Configuring OHW-RC as Standalone Web Application

After all files have been put in the right locations, the OHW administrator still needs to modify some configuration files to make OHW-RC 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-RC 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 18.5, "Configuring OHW-RC 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 9, "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-RC 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-RC. 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>

18.8 Deploying OHW-RC as part of a Web Application

One way to deploy the OHW-RC 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-RC then could be deployed as one of the Web projects within the existing application.

When you deploy OHW-RC as part of an existing web application, the web application and OHW-RC help system, both, share the same web.xml. This could limit the fine tuning of OHW-RC help system and may cause conflict with your application. It is recommended that you deploy OHW-RC separately from your web application, and then link the help system with your application. For more information, see Section 18.7, "Deploying OHW-RC 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 20.1, "Integrating Online Help With ADF Faces Application".

18.8.1 Installing the OHW-RC 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).

18.8.2 Configuring OHW-RC as Part of Web Application

After all files have been put in the right locations, the OHW administrator still needs to modify some configuration files to make OHW-RC 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-RC front servlets and JSF filter.

    Since the OHW-RC is part of existing application, the OHW-RC administrator needs to make sure 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 9, "Oracle Help for the Web Configuration File".

18.9 Deploying Multiple Help Instances in a Web Application

OHW-RC 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-RC configuration. The deployment of multiple help instances for OHW-RC is achieved by providing an OHW-RC front servlet that forwards the request to the JSF servlet.

18.9.1 Application and OHW-RC Configuration Files and Setup

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

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

<!-- 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-RC front servlets called product1 and product2. Each servlet can load a different OHW-RC configuration file that will determine 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-RC context root that has product1 at the end portion of the URL, it will be re-routed to this servlet. Similarly, the product2 is mapped to the URL pattern of /product2/*.

18.9.2 Running the application

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

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

The above URL will call the servlet product1 that will load the OHW-RC configuration file from /helpsets/product1/ohwconfig.xml and will be redirected to a URL like this:

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

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

  Previous
Previous 		 Next
Next
  Go To Table Of Contents
Contents		 Go To Index
Index