JavaHelp^TM 1.0 - Merge

Copyright 1998-1999 Sun Microsystems

Introduction

JavaHelp provides a mechanism for merging HelpSets. For example, when two indexes are merged, the second index is appended to the first index. Constituent HelpSets can be dynamically removed from the merged HelpSet, even while the merged HelpSet is displayed. When HelpSets are merged there is always a master HelpSet into which other HelpSets are marged.

In addition, a HelpSet file can use the <subhelpset> tag to statically include HelpSets, this behavior is identical to adding the subhelpset to the enclosing HelpSet, except that if the subhelpset file does not exist, it is ignored.

Here are some examples where merging might be appropriate:

An application suite may be comprised 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.

A Builder tool uses JavaBeans to construct programs. Each JavaBean provides help information about its functionality. The help information of the constituent JavaBeans can be listed in the TOC, in the index, and be accessible to searches.

When JavaBeans are used to dynamically extend the functionality of an application (sometimes this functionality is described as plug-in) the JavaBeans contain help information that conforms to the nature of the application. This help information can be meaningfully merged before being presented to the user.

The API

The basic API comprises the HelpSet.add(HelpSet) method, and its corresponding HelpSet.remove(HelpSet) method. These methods fire HelpSetEvent events to the HelpSetListeners that have registered interest in them. This is how the ComponentUIs for TOC, Index, and Search views are notified of these changes and react to them.

When a HelpSet A is added to a HelpSet B, all the views in A are compared to the views in B; if a view in A has a name that is the same as another view in B, then it is considered for merging into B, otherwise it is not.

When considering merging a view V_a into a V_b the following happens:

The navigator N_b of V_a is obtained.
N_b.canMerge(V_a) is invoked to determine if the views can be merged.
If then can be merged, then N_b.merge(V_a) is invoked.

If later the HelpSet A is removed from HelpSet B:

N_b.remove(V_a) will be invoked.

Merging TOCs

TOCView and JHelpTOCNavigator implement a merging rule that allows any TOCView with the same name to be merged. The resulting presentation adds the new TOC data as the last subtree of the top level of the original TOC.

A TOCView may have no <data> tag; such a view shows as an empty tree. This is useful for what is sometimes called "dataless" master views into which other views can merge.

Merging Indices

IndexView and JHelpIndexNavigator implement a merging rule that allows any IndexView with the same name to be merged. The resulting presentation adds the new index data as the last subtree of the top level of the original index. No attempt to sort the data is provided in the standard types.

An IndexView may have no <data> tag; such a view shows as an empty tree.

Merging Full-Text Search Databases

SearchView and JHelpSearchNavigator implement a merging rule that allows any SearchView with the same name to be merged. The resulting presentation adds the SearchEngine from the new view to the previous list--query results from all the SearchEngines are collated and presented together.

A SearchView may have no <data> tag; such a view produces no matches against any queries.

JavaHelp^TM 1.0
Send your comments to javahelp-comments@eng.sun.com
Last modified: Mon Apr 12 16:46:00 MDT 1999