JavaHelp^TM 1.0 - Overview

Copyright 1998-1999 Sun Microsystems

Introduction

JavaHelp^TM is an online help system specifically tailored to the Java platform. JavaHelp consists of a fully featured, highly extensible specification and an implementation of that specification written entirely in the Java language.

JavaHelp enables Java developers to provide online help for:

• Applications (both network and stand-alone)
• Applets
• JavaBean components
• Desktops
• HTML pages

Features

The main features of JavaHelp are:

Help Viewer	The standard JavaHelp viewer consists of a toolbar and two panes: Content pane Displays help topics formatted using HTML. Navigation pane A tabbed interface that allows users to switch between the table of contents, index, and full text search displays.
Table of contents	XML-based. Collapsible/expandable display of topics in the help system. Supports unlimited levels and merging of multiple TOCs.
Index	XML-based. Supports merging of multiple indexes.
Full text search	The full text of the content is searchable. Different engines can be used.
Compression and encapsulation	Encapsulation and compression are optional. Uses the standard Java JAR format to encapsulate the entire help system into a single, optionally compressed file.
Embeddable help windows	Help windows (individually or in combination) can be embedded directly into application interfaces.
Customization	JavaHelp is designed to permit great flexibility in customizing both the user interface and functionality.

The reference implementation adds the following to this list:

Flexible Search Engine	The full text of the content can be searched with a flexible search engine that supports multi-word queries.
PopUps and Active Content	PopUps can be obtained by embedding lightweight Java components in HMTL pages. Active content (e.g. a button that when pressed can act on the application) can be implemented using the same mechanism.

Serialization

Serialized objects of JavaHelp Swing components will not be support in V1.0. A future release of JavaHelp will provide full serialization including support for long term persistence.

Supported Platforms

JavaHelp 1.0 is a standard extension for both the JDK1.1 and the JDK1.2 platforms.

Although JDK1.1 is in wider use at the time of writing of this document, JDK1.2 is fundamentally a better platform and it offers many features useful to JavaHelp customers, including:

• The jar: protocol in the platform, which provides a general and consistent (and efficient) way to refer to files within a JAR file.
• Temporary files, providing improved full-text search performance.
• More flexible ClassLoader classes that can, for example, easily be used to create a ClassLoader instance to a given URL.
• An improved security model.
• Safe access to the SystemEventQueue from an Applet to support some of the Context-Sensitive features.
• Improved I18N support, including input methods.
• Printing support.
• Other improved set of APIs, including sound, 2D and 3D graphics.

The JavaHelp specification has two main parts:

API	The interface between the application and the help system
File formats	Formats of the files that are part of the help system (HelpSet, table-of-contents, map, index, search database)

API Structure

Main Concepts

Below we describe the fundamental concepts in the specification. More details are available in other parts of this specification and in the javadoc comments of the classes.

HelpSet

A HelpSet is a collection of help content (topics), navigational views, and mapping information. A HelpSet can contain other HelpSets which are merged merged together.

HelpSet File

The HelpSet file describes a HelpSet and contains:

• Title and other global information
• Map information that associates topic IDs with topic files
• One or more navigational views on the content

HelpBroker

A Help Broker object is the abstraction of the presentation to a HelpSet. An application can use a HelpBroker object to interact programmatically with the presentation of information. The default HelpBroker implementation uses a Swing JFrame, but other implementations are possible (for example, embedding help objects).

JavaHelp provides "context views" for navigating through content information; for example, most HelpSets will have a view displaying a Table of Contents. A view has a name, a NavigatorView Class identifying its behavior, some information (e.g. URLs, arguments) used by the instance, and a JHelpNavigator which is a GUI component that presents the view to the user. Navigational views are visible to the JavaHelp APIs and the client can request to make a specific view active.

The view's class defines what data it reads, its format, how it will be presented visually, and it also defines the merging rules. A view is a subclass of NavigatorView. The createNavigator() method of a view returns a component that is used to graphically present the view; for the standard views this component is a Swing component, specifically, a subclass of JHelpNavigator.

Any JavaHelp implementation must support the standard NavigatorView classes, but a HelpSet may include views with other classes, as long as they are available (technically, as long as their definitions are available to the ClassLoader instance of the HelpSet). In many cases this means they are either in the implementation of JavaHelp, in the CLASSPATH, or they are listed in the ARCHIVE attribute of an APPLET.

Standard Help Views and Help Navigators

All JavaHelp implementations must provide the following classes:

javax.help.TOCView javax.help.JHelpTOCNavigator	NavigatorView for parsing Table of Contents data and the JHelpNavigator for its presentation.
javax.help.IndexView javax.help.JHelpIndexNavigator	The NavigatorView and JHelpNavigator for parsing and presenting Index data.
javax.help.SearchView javax.help.JHelpSearchNavigator	The NavigatorView and JHelpNavigator for interacting with a search engine using the javax.help.search.* classes.

The formats used by the TOC and the Index Navigators are described in FileFormat. The Search Navigator interacts with its data through a search engine that extends the SearchEngine class; one of the Search View arguments is the class name of the search engine, the rest of the data is passed directly to the search engine.

Help information (topics) is described through a collection of URLs. These URLs may be files, may be within a JAR file, or they may be generated dynamically by the server.

Content information is presented depending on its (MIME) type. JavaHelp system implementations are required to provide viewers for HTML3.2 content, but there is a registration mechanism in JHelpContentViewer that is built upon the corresponding mechanism in JEditorPane in the Swing package.

JavaHelp authors can use a number of protocols in the URLs when they are used in the HelpSet file and map files. The specific protocols available depend on the underlying platform. For example, JDK1.1 provides file:, http:, ftp:, while JDK1.2 adds the jar: protocol which provides access to files within a JAR file. Specific implementations may support additional URL formats.

Applications (or navigational data) do not usually directly reference content files, instead they usually reference them through string identifiers (IDs). This use of IDs insulates content development from application development. Identifiers are mapped to content files in a map file. Multiple map files can be combined within a HelpSet, but an identifier must be unique within a HelpSet in the resulting combined map.

JavaHelp contains a simple search API in the package javax.help.search. This package provides creation and access to the search databases used by JavaHelp. Different search engines will be identified as subclasses of javax.help.search.SearchEngine. The search engine included in the JavaHelp reference implementation is com.sun.java.help.search.DefaultSearchEngine.

Merging

In simple applications, the help data may be described in a single HelpSet file. Other situations are best described as a collection of HelpSets, for example:

• An application can merge help information available locally on a user's disk, with information on a web site
• Product suites can merge help information when constituent applications are installed
• HelpSets from an application's constituent Beans can be merged for a unified presentation

JavaHelp 1.0 provides a basic mechanism for merging the contents of several HelpSets, the resulting HelpSet merges the map information and the navigational views. See Merge for additional information.

The JavaHelp system is designed so it can be extended in several dimensions:

• The JHelpContentViewer registration mechanism can be used to provide new content viewers
• The NavigatorView and JHelpNavigator mechanisms can be used to provide new file formats, or new presentations
• The javax.help.search classes can be used to replace search engines.

It is often important to be able to update a product's online help after it has been released. The JavaHelp system supports this in several ways--it is possible to entirely replace the information (if in a JAR), or replace parts of it (if spread over multiple files).

Because you can refer to multiple maps in the HelpSet file, the JavaHelp system provides additional flexibility in this update process. The HelpSet file can extend these maps, making it possible to modify the mapping without modifying any existing map files (which may be inside a JAR file). Finally, since the URL protocols support remote access, if the application is running in a connected environment, it is possible to keep some information remotely.

In summary, the JavaHelp system specifies the following file formats:

• HelpSet encapsulation and compression using JAR files
• HTML topic files - HTML 3.2 minus the APPLET tag (use the OBJECT tag to implement lightweight JComponents in the reference implementation)
• HelpSet file
• Map files
• Standard navigation view formats (TOC, index, search)

More information is available in FileFormat.html.

An Example

The following is an example of a HelpSet file.

    <?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">

	<!-- the title for the helpset -->
	<title>An Example</title>

	<!-- maps -->
	<maps>
	    <homeID>top</homeID>
	    <mapref location="jar:file:/c:/Program Files/JWS3.0/JWS3.0.jar!/TheMap.map" />
	</maps>

	<!-- A TOC view -->
	<view>
	    <name>TOC</name>
	    <label>Table Of Contents</label>
	    <type>javax.help.TOCView</type>
	    <data>jar:file:/c:/Program Files/JWS3.0/JWS3.0.jar!/TOC.xml</data>
	</view>

	<!-- Another TOC view; note that it has a different name -->
	<view>
	    <name>LocalTOC</name>
	    <label>Appendix One</label>
	    <type>javax.help.TOCView</type>
	    <data>jar:file:/c:/Program Files/JWS3.0/JWS3.0.jar!/LocalTOC.xml</data>
	</view>
	
	<!-- An Index view -->
	<view>
	    <name>Index</name>
	    <label>Index</label>
	    <type>javax.help.IndexView</type>
	    <data>jar:file:/c:/Program Files/JWS3.0/JWS3.0.jar!/Index.xml</data>
	</view>

	<!-- A Search view; note the engine attribute -->
	<view>
	    <name>Search</name>
	    <label>Search</label>
	    <type>javax.help.SearchView</type>
	    <data engine="com.sun.java.help.search.SearchEngine">
              jar:file:/c:/Program Files/JWS3.0/JWS3.0.jar!/SearchData
	    </data>
	</view>

    </helpset>

The HelpSet file starts a DOCTYPE identifying the DTD for the file. The DTD is versioned to allow for future changes. Next follows the title of the HelpSet.

The next section provides information about ID->content file mapping. An ID is given indicating what information within the HelpSet to show by default. Next a mapref tag indicates where to locate the map. In our case the mapfile is contained within a JAR file on the local disk.

The next three sections of the HelpSet file provide information about different views of the content information. The first view, "TheTOC", is in a local disk. The next section is a different Table of Contents view, ("MyLocalTOC"), that uses the same information as the first view, while the next section is an index on the local disk. The final section defines search information.