Oracle Help File Formats	Contents	Previous	Next

Dynamic Mapping of Topic IDs to Files

If your helpset uses a simple convention to map between topic IDs and map files, you may be able to significantly enhance Oracle Help's memory usage and startup time with dynamic mapping.

As of OHJ 4.2.1 and OHW 2.0, Oracle Help supports a new engine attribute on the <mapref> subelement of the helpset's <maps> area. By setting the engine attribute, one can use a custom engine to parse the map file and create an object used to map between topic IDs and files. In fact, by using certain engines, you may actually eliminate the map file altogether.

The engine attribute is optional, so if it goes unspecified, Oracle Help will expect the location attribute to be set on the <mapref>, and the map file will be parsed and stored in the same manner as it was in older versions of Oracle Help.

However, Oracle Help supports two engines that support certain common conventions for mediating between topic IDs and files:

oracle.help.engine.XMLMapFixedConventionEngine
oracle.help.engine.XMLMapConventionEngine

If those two engines do not satisfy your needs for dynamic mapping, you can write a custom implementation of oracle.help.engine.DataEngine.

`oracle.help.engine.XMLMapFixedConventionEngine`

In many cases, for a filename of myfile.html, the corresponding topic ID is just myfile_html. If your map file is simply a long, redundant list of obvious topic mappings of this form, you will want to set the engine attribute on <mapref> to oracle.help.engine.XMLMapFixedConventionEngine.

If you are using OHJ 4.2.1 or higher or OHW 2.0 or higher, setting the engine to this value will make your old map file expendable. However, if your help content may be viewed using an older version of Oracle Help, you should keep your old map file around so that the older versions of Oracle Help can fall back to the standard mechanism of topic mapping.

If you are concerned about the help system's memory usage and startup time, it is strongly recommended that you use this new engine. Doing so implies that your map file is never read, and therefore its contents are not stored in memory. However, there is one caveat to the engine's use:

All help content (HTML files) must reside in the same directory as the helpset file. In addition, any subhelpsets must also reside in the same directory as the master helpset file. Subdirectories for subhelpsets are not permitted because the help system will not be able to find your content unless it is in the same directory as the master helpset. However, different helpsets may reside in different directories.

`oracle.help.engine.XMLMapConventionEngine`

If on your <mapref> element you set engine to be oracle.help.engine.XMLMapConventionEngine you may define your own topic name convention in your map file. For example, consider the following <maps> definition in a helpset:

<maps>
  <mapref location="map.xml" engine="oracle.help.engine.XMLMapConventionEngine"/>
</maps>

The XMLMapConventionEngine supports the standard mechanisms for setting up topic ID and window type mappings. However, it also supports the new <topicNameConvention> element.

If using the XMLMapConventionEngine, your map.xml may resemble the following:

<map version="1.1">
  <topicNameConvention urlbase="http://www.example.org/help">
    <text>beginningText</text>
    <filename/>
    <text>_</text>
    <extension/>
    <text>endingText</text>
  </topicNameConvention>
</map>

The idea of the <topicNameConvention> is simple.You simply specify how your topic IDs are structured. If you set the urlBase attribute on the <topicNameConvention>, all help content files are assumed to be located at that URL. If all of your topic IDs begin with a string that is not a part of the filename or extension, you can specify a value for <text> at the beginning of the convention. Then you must specify either the <filename/> or the <extension/> to indicate whether the filename or extension appears first in your topic name convention. Then you can specify the <text> that separates the filename and extension. Either the <filename/> or the <extension/> should follow to indicate whether the filename or extension appears second in the convention. A final <text> may be specified if all topic IDs end with some text that is not part of the filename or extension.

According to the above topic name convention, the topic ID of beginningTextmyfile_htmlendingText would resolve to the file http://www.example.org/help/myfile.html. Had the urlBase attribute gone unspecified, it would be assumed that myfile.html is in the same directory as the helpset file.

If you want to set up some standard topic mappings and window types in your map file but still use the topic name convention provided by the XMLMapFixedConventionEngine, you could define a topicNameConvention in your map file as follows:

<map version="1.1">
  <topicNameConvention>
    <filename/>
    <text>_</text>
    <extension/>
  </topicNameConvention>
  <mapID etc.../>
</map>

Note that for the above convention (and the XMLMapFixedConventionEngine), the text that separates the filename and extension may actually appear multiple times in the topic ID. For example, consider the topic my_file_html. The engines assume that the separator between filename and extension is actually the last appearance of the "_" character in the topic ID. Therefore, the topic resolves to my_file.html.

Optimizing Dynamic Maps

Dynamic mapping of topic IDs to files can result in great improvements in your help system performance. However, context sensitive help calls to specific topics may take a long time to resolve if your library includes many helpsets.

The fundamental reason for this is that the convention-based mapping engines return URLs for topic IDs even if the URLs do not resolve to anything. Because of this, context sensitive help calls go through each helpset in the library and check whether the URLs generated by the engines actually resolve.

In the worst case, for a single context sensitive help call, the help system will attempt to connect to as many URLs as there are helpsets in your library. However, Oracle Help provides a simple remedy to alleviate the problem. If you set an engine on your <mapref> element, you may also set the engineParams attribute.

If you use the XMLMapConventionEngine or the XMLMapFixedConventionEngine, you may want to set engineParams to be a space-separated list of prefixes for all the topics in your helpset. For example, if all the topics in your helpset begin with either oh or help your mapref would look like the following:

<mapref engine="XMLMap..." engineParams="oh help">

Setting engineParams for either of the convention-based engines ensures that the helpset will only try to resolve topics if they start with a valid prefix (thereby preventing an attempted connection to an URL that we know will not resolve). Failure to set engineParams will not break your help system, but performance will not be optimal.