13 Introduction to Oracle Help for Java Developer's Kit

The Oracle Help for Java Developer's Kit (OHJDK) is a set of Java components and an API for developing and displaying HTML-based help content in a Java environment. It includes the Oracle Help for Java (OHJ) engine and additional tools necessary for implementing context-sensitive help in Java applets and applications.The Oracle Help for Java engine is a full-featured Java-based help system for Java applications and applets. It provides pure Java components for navigating and displaying context-sensitive help. Oracle Help for Java is available for free, and may be redistributed as the help system for your application (see the license distributed with the release).Oracle Help for Java supports help content in several file formats, including extensions of the Sun Microsystem's JavaHelp and Microsoft's HTML Help standards. If you are authoring help content without using a help authoring tool, it will be helpful to read Oracle Help File Formats. If you are using a third party help authoring system that supports OHJ, refer to the documentation provided.

13.1 Oracle Help for Java Runtime in JDeveloper

The Oracle Help for Java runtime library, ohj.jar, is distributed as part of JDeveloper. Developers integrating Oracle Help for Java with their applications can modify their project settings to add the Oracle Help for Java library as a dependency. The full Oracle Help for Java release including sample code, helpset authoring wizard, indexer, and demos is available at no cost from the Oracle Technology Network (http://www.oracle.com/technology/index.html) under Oracle Help Technologies.

13.2 Getting Started with the OHJDK

This section describes the contents of the OHJDK and tells how to set up for developing OHJ help systems. It contains the following subsections:

Section 13.2.1, "Installing OHJDK"
Section 13.2.2, "Contents of an OHJDK Release"
Section 13.2.3, "Setting the Java CLASSPATH for OHJDK Development"

13.2.1 Installing OHJDK

The following steps describe OHJDK installation process:

Download the latest Oracle Help for Java Developer's Kit from OTN. For Windows, you may download the Windows executable file or Executable JAR file. For Solaris or UNIX, download the binary file.
In Windows, double click the Windows executable file or executable JAR file to start the installation wizard. By default, the OHJDK is installed at C:\Program Files\ohelp location. For Solaris and UNIX, run the binary file to start the installation wizard.
Open the install folder and verify the files as described in Section 13.2.2, "Contents of an OHJDK Release".

13.2.2 Contents of an OHJDK Release

The OHJDK includes the compiled libraries for the OHJ engine as well as libraries for the authoring tools and demonstrations. These libraries are distributed in JAR (Java ARchive) format. The OHJDK also includes documentation, including this document.

The files are discussed in the following sections:

Section 13.2.2.1, "OHJ Engine"
Section 13.2.2.2, "Authoring Tools"
Section 13.2.2.3, "Demonstration Files"
Section 13.2.2.4, "Documentation"

13.2.2.1 OHJ Engine

These files contain binary files for the OHJ engine implementation and its dependencies. You must redistribute these files with your product application.

Table 13-1 OHJ Binaries

File	Contents
`helpversion_num.jar`	The help engine optimized binaries.
`oracle_ice.jar`	Oracle's customized version of the ICEbrowser from ICEsoft Technologies, Inc. The OHJ engine uses the ICEbrowser for displaying HTML topics.

13.2.2.2 Authoring Tools

The following JAR files contain the implementation for the Helpset Authoring Wizard and the Text Search Indexer. These files are not intended for distribution with your product application.

Table 13-2 OHJ Authoring Tools

File	Contents
`helpwizard-version_num.jar`	Helpset Authoring Wizard implementation. Authors can run the Helpset Authoring Wizard using batch files created in the bin directory of their OHJDK installation.
`helpindexer-version_num.jar`	OHJ Text Search Indexer implementation. Authors can use the Full-Text Search Indexer to process and create Oracle Help search index (`.idx`) files.

13.2.2.3 Demonstration Files

The following JAR file contains the demonstration programs distributed with the OHJDK. This file is not intended for distribution with your product application.

Table 13-3 OHJ Demonstration JAR File

File	Contents
`helpdemo-version_num.jar`	Demonstration binaries and source code, plus sample documentation in HTML and the Oracle Help control file formats.

To run the demonstration programs, execute the batch files located in the bin subdirectory of your OHJDK installation. The OHJ installer for Windows adds shortcuts to the Windows Start Menu. The sample content used by the demo programs is located in the demodoc subdirectory.

When integrating OHJ with your application, it may be helpful for you to examine the source code for the demonstration programs (located in the helpdemo-version_num.jar file. The following two demos will be particularly helpful:

Table 13-4 OHJ Demonstration Files

File Contents

File	Contents
`ChoiceDemo.java` (OHJ Features Demo)	Sample Java code that illustrates the following features: Constructing the Help object Adding helpsets (data) Displaying the OHJ navigator window Displaying multiple helpsets
`CSHDemo.java` (Context-Sensitive Help Demo)	Sample Java code that illustrates the following features: Launching the help system from a menu Associating help topics with particular application controls Enabling the F1 key to launch help Implementing right-click pop-up menu help

ChoiceDemo.java

(OHJ Features Demo)

Sample Java code that illustrates the following features:

Constructing the Help object
Adding helpsets (data)
Displaying the OHJ navigator window
Displaying multiple helpsets

CSHDemo.java

(Context-Sensitive Help Demo)

Sample Java code that illustrates the following features:

Launching the help system from a menu
Associating help topics with particular application controls
Enabling the F1 key to launch help
Implementing right-click pop-up menu help

13.2.2.4 Documentation

The following documentation is included with the OHJDK:

Table 13-5 OHJ Documentation

Document	Content	Location in OHJDK release
OHJ API Reference Documentation	Reference documentation for the OHJ Application Programming Interface (API), provided as JavaDoc.	The doc/javadoc subdirectory of the OHJDK installation. To view the API documentation, open the `index.html` file in an HTML browser.
Oracle Help Guide	This document	The doc subdirectory of the OHJDK installation.

13.2.3 Setting the Java CLASSPATH for OHJDK Development

To develop with the OHJDK, you must add the OHJ engine libraries and toolkit dependencies to your environment class path.

For example:

On Windows 2000 or XP, set the CLASSPATH variable in the Environment Variables dialog, accessed from the Advanced tab of the System Properties control panel.
On Windows NT, set the CLASSPATH variable in the Environment tab of the System Properties control panel.
On Windows 95/98, use the SET command in your autoexec.bat file.
On UNIX, use the setenv command to set an environment variable for your shell.

Consult the documentation for your Java Virtual Machine (JVM) and operating system to determine how to set the CLASSPATH variable.