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

Deploying OHW for Multiple Locales

The OHW 1.x architecture requires one instance of the OHW servlet per locale. Thus, in order to provide help in multiple languages, it is necessary to have multiple instances of the OHW servlet. Note that this does not mean that you need to set up multiple web applications or enterprise applications.

In the web.xml file for your OHW web application, you can define multiple named instances of the OHW servlet, and each instance can have a different OHW Configuration file that would define the locale of the OHW instance and load the localized helpset(s) for that servlet. Then, you would define a servlet mapping for each instance of the OHW servlet, typically the mappings are language codes like /en/*, /ja/*, /de/*, etc. For example, here is a web.xml file with three instances of the OHW servlet, for English (en), Japanese(ja), and German(de) content.

<?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>en</servlet-name>
    <servlet-class>oracle.help.OHW</servlet-class>
    <init-param>
      <param-name>configFileName</param-name>
      <param-value>/helpsets/help_en/ohwconfig.xml</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>en</servlet-name>
    <url-pattern>/en/*</url-pattern>
  </servlet-mapping>


  <servlet>
    <servlet-name>ja</servlet-name>
    <servlet-class>oracle.help.OHW</servlet-class>
    <init-param>
      <param-name>configFileName</param-name>
      <param-value>/helpsets/help_ja/ohwconfig.xml</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>ja</servlet-name>
    <url-pattern>/ja/*</url-pattern>
  </servlet-mapping>

  <servlet>
    <servlet-name>de</servlet-name>
    <servlet-class>oracle.help.OHW</servlet-class>
    <init-param>
      <param-name>configFileName</param-name>
      <param-value>/helpsets/help_de/ohwconfig.xml</param-value>
    </init-param>
  </servlet>
  
  <servlet-mapping>
    <servlet-name>de</servlet-name>
    <url-pattern>/de/*</url-pattern>
  </servlet-mapping>

</web-app>

Note that each OHW servlet instance is given a name; in the example, the language code is used as the name. The configFileName inititalization parameter for each servlet points to a different ohwconfig.xml file. Each servlet has a <servlet-mapping> that maps the servlet of the given name ("de") to a url pattern (/de/*). This sets up a servlet mapping for each set of localized help. In this example, the following URLs would be valid:

  http://<hostname>:<port>/<web-app-context-path>/en/
  http://<hostname>:<port>/<web-app-context-path>/ja/
  http://<hostname>:<port>/<web-app-context-path>/de/

Note that the OHW servlet is not initialized until the first request. For example, if no user ever accesses the URL for the Japanese content, the OHW Servlet instance will never load the Japanese helpsets. Therefore, OHW only uses memory on the server for the content that is actually being used.

If You Are Using UIX

If you are using OHW with an application built with Oracle UIX technology, register the URL you set up for each locale with the the oracle.cabo.ui.data.help.OracleHelpProvider using the registerLocaleSpecificServlet() method. Here is the Javadoc for that method:

`registerLocaleSpecificServlet()` Method
`registerLocaleSpecificServlet(Locale locale, String localeSpecificServletLocation)` Register a different OHW servlet instance for a given locale. When a request comes in from the end user's browser with a specific locale, the `OracleHelpProvider` will attempt to find a HelpProvider registered for that Locale. If a match for language, country, and variant cannot be found, it checks if a Locale has been registered with matching language and country. If a language and country match cannot be found, it checks if a Locale has been registred for just the language. If no match can be found, it uses the default OHW servlet instance registered upon creation to handle the request. Parameters: `locale` - the locale for which this OHW instance should be used `localeSpecificServletLocation` - the location of the OHW servlet

registerLocaleSpecificServlet() Method

registerLocaleSpecificServlet(Locale locale, String localeSpecificServletLocation)

Register a different OHW servlet instance for a given locale. When a request comes in from the end user's browser with a specific locale, the OracleHelpProvider will attempt to find a HelpProvider registered for that Locale. If a match for language, country, and variant cannot be found, it checks if a Locale has been registered with matching language and country. If a language and country match cannot be found, it checks if a Locale has been registred for just the language. If no match can be found, it uses the default OHW servlet instance registered upon creation to handle the request.

Parameters:

locale - the locale for which this OHW instance should be used

localeSpecificServletLocation - the location of the OHW servlet

When you use the UIX HelpProvider mechanism to implement context-sensitive help, you databind the destination of your link or button as in the example data:destination="topic1@ui:helpTopics". The OracleHelpProvider is passed the topic ID topic1 and returns a URL for displaying that topic. The OracleHelpProvider examines the browser locale of the HTTP request and uses that to pick the best matching base URL from the set of URL's registered with the registerLocaleSpecificServlet() method.