#
JavaHelpTM 1.0 - Overview

## Copyright 1998-1999 Sun Microsystems

## Introduction

JavaHelpTM 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

This document is an overview of the JavaHelp specification. API documentation generated using `javadoc` can be found starting at api/index.html

## 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 Specification

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

The classes and methods in JavaHelp 1.0 can be partitioned depending on the tasks so that clients of the API need only use as much as they need. The following are the most useful collections:

Basic Content Presentation | `HelpSet` and `HelpBroker` are used to locate and create HelpSets and then to present these to the user using the default HelpBroker.
Complete Access to JavaHelp Functionality | A number of classes provide for access to Help Data and for control of the navigation of the online content. For example, the `NavigatorView` class provides access to the data in a Navigator View.
Full-Text Search | The classes in the `javax.help.search` package provide a simple API for full-text search that can also be used independently of help applications.
Swing Classes | Finally, JavaHelp 1.0 defines Swing components for Navigators, Content Viewer and Help Viewer which can be embedded into an Application if desired. Custom Navigators are also presented to the API as Swing components.

## 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).

### Help Views and Help Navigators

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.

### Content files

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.

### URL Protocols

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.

### Map File

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.

### Search

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.

### Extensibility

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.

For more details see Customization

### Updating Help Information

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.

## File Formats

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.

JavaHelpTM 1.0
Send your comments to javahelp-comments@eng.sun.com
Last modified: Mon Apr 12 19:13:58 MDT 1999