Merging HelpSets

The JavaHelp system provides a mechanism for merging HelpSets. You can use the merge functionality to append TOC, index, and full-text search information from one or more HelpSets to that of another HelpSet.

An example of where this functionality might be useful is in an application suite. The application suite may consist of a collection of constituent applications. As constituent applications are purchased and installed, their help information can be merged with help information from the other applications in the suite.

HelpSets can be merged statically or dynamically.

Static Merging

To merge HelpSets statically, add <subhelpset> tags to a master HelpSet file to specify other HelpSets that you want to merge with the original HelpSet. The merge operation is performed whenever the containing HelpSet is instantiated.

In the following simple example, HelpSet2 is merged with HelpSet1 to produce the unified TOC display shown below:


-HelpSet1.hs-

   <?xml version='1.0' encoding='ISO-8859-1' ?>
   <!DOCTYPE helpset
     PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
            "http://java.sun.com/products/javahelp/helpset_1_0.dtd">
   <helpset version="1.0">
      <title>HelpSet 1</title>
      <maps>
        <homeID>hs1_file1</homeID>
        <mapref location="hs1.jhm" />
      </maps>
      <view>
         <name>TOC</name>
         <label>Table Of Contents</label>
         <type>javax.help.TOCView</type>
         <data>hs1TOC.xml</data>
      </view>
     <subhelpset location="HelpSet2.hs" />
   </helpset>


-HelpSet2.hs-

   <?xml version='1.0' encoding='ISO-8859-1' ?>
   <!DOCTYPE helpset
     PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
            "http://java.sun.com/products/javahelp/helpset_1_0.dtd">
   <helpset version="1.0">
      <title>HelpSet 2</title>
      <maps>
        <homeID>hs2_file1</homeID>
        <mapref location="hs2.jhm" />
      </maps>
      <view>
         <name>TOC</name>
         <label>Table Of Contents</label>
         <type>javax.help.TOCView</type>
         <data>hs2TOC.xml</data>
      </view>
   </helpset>

The HelpSet that contains the <subhelpset> tag is considered to be the master HelpSet--all HelpSets are merged with (appended to) the master HelpSet.
When HelpSets are merged, only views with the same name (<name> tag) as a view in the master HelpSet file are merged. Note that in the example above, both views are named "TOC". Any views in the sub-HelpSets that do not match the views in the master HelpSet are not displayed.
Multiple <subhelpset> tags can be included in a HelpSet file. HelpSets are appended in the order in which they occur in the HelpSet file. If a HelpSet specified in a <subhelpset> tag is not found, it is ignored and no error is issued.
The <subhelpset> location attribute takes a URL as its argument.
Indexes are merged in the same manner as TOCs--by appending the merged indexes to the master HelpSet.
Merged search databases are searched sequentially, however, query results are collated and presented together.

Dataless Master HelpSets

It is possible to create dataless master HelpSets that do not contain any view or map data of their own--a dataless master serves only as a container for specifying sub-HelpSets. This is accomplished by omitting the <data> for the views. All the notes listed above still apply.

The following example HelpSet file could serve as an dataless master for a suite of applications. The JavaHelp system constructs a help display with whichever of the application sub-HelpSets (app1.hs - app2.hs) are found installed on the user's system:


   <?xml version='1.0' encoding='ISO-8859-1' ?>
   <!DOCTYPE helpset
     PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
            "http://java.sun.com/products/javahelp/helpset_1_0.dtd">

   <helpset version="1.0">
      <!-- title -->
      <title>JavaHelp System User's Guide</title>

      <!-- views -->
      <view>
         <name>TOC</name>
         <label>Table Of Contents</label>
         <type>javax.help.TOCView</type>
      </view>
 
      <view>
         <name>Index</name>
         <label>Index</label>
         <type>javax.help.IndexView</type>
      </view>
 
      <view>
         <name>Search</name>
         <label>Search</label>
         <type>javax.help.SearchView</type>
      </view>

      <subhelpset location="app1.hs" />
      <subhelpset location="app2.hs" />
      <subhelpset location="app3.hs" />
      <subhelpset location="app4.hs" />

   </helpset>

A master HelpSet can contain a mixture of both dataless and datafull views.

Dynamic Merging

HelpSets can also be merged programmatically using the JavaHelp API.

The basic API consists of the add(HelpSet) method, and its corresponding remove(HelpSet) method. These methods fire HelpSetEvent events to the HelpSetListeners that have registered interest in them. The ComponentUIs for the TOC, index, and search views register for these events and react to changes.

The semantics of merging is implemented by individual NavigatorViews and JHelpNavigators. There are three basic methods:

canMerge(NavigatorView)
merge(NavigatorView)
remove(NavigatorView)

The canMerge(NavigatorView) method is present in both NavigatorView and JHelpNavigator, the JHelpNavigator method just calls into its corresponding NavigatorView method. The other two methods are present only in JHelpNavigator.

For more information about these classes and methods, refer to the JavaHelp API documentation. API information can be viewed using a web browser (doc/api/overview-summary.html) or by using the demos\bin\apiviewer command.

A demonstration program (demos\bin\merge) is included with the JavaHelp system release. This program demonstrates how HelpSets can be merged and removed dynamically. The sources for that program are available in demos\src\sunw\demo\merge.