JAR Files

This topic describes how JAR files are used in the JavaHelp system.

Using JAR Files

After you create your help information, you will usually encapsulate it into a single file and compress it for delivery to your users. The JavaHelp system uses the JAR (Java ARchive) format for encapsulation and compression. The JAR file format is based on the popular ZIP file format. The JavaHelp system automatically extracts information from the JAR file when it is required.

Until support is available from GUI-base help authoring tools, the jar command (located in the JDK bin folder) must be used from a command-line prompt to create, read, and extract data from JAR files.

Sample Help Hierarchy

The following sections refer to this sample help hierarchy:

The jar Command

The jar command syntax is: 

    jar [ctxvfm] [jar-file] [manifest-file] files ...
    Option flags are:
        c  create new archive
        t  list table of contents for archive
        x  extract named (or all) files from archive
        v  generate verbose output on standard error
        f  specify JAR file name
        m  include manifest information from specified 
	   manifest file
For more detailed information about the jar command or format, please refer to http://java.sun.com/beans/jar.html.


The jar command is located in the bin directory of the JDK.

Creating JAR Files

To create a JAR file from your help files, make the top level help folder the current folder. The jar command descends recursively through the different directories and copies all of the files to the JAR file.

Use the following steps to create a JAR file named my_help.jar from the hierarchy example above,:

  1. C:\> cd ...\help (where "..." is the path above the \help folder)
  2. C:...\help> jar -cvf my_help.jar *
The jar -cvf command copies all the files in the \help folder and in all folders hierarchically beneath it into a JAR file named my_help.jar. As the command creates the JAR file, it reports its progress with output like the following: 
  adding: my_helpset.hs (in=5757) (out=2216) (deflated 61%)
This indicates that the file my_helpset.hs was added to the JAR file and compressed 61% (from 5272 bytes to 2150 bytes).

When you create a JAR file, the jar command automatically creates a manifest file for you. The manifest file consists of a list of files present within the archive itself.

Listing JAR Files

Use the t option to list the files included in a JAR file: 


C:\> jar -tvf my_help.jar
  5272 Fri Apr 03 14:48:04 PST 1998 META-INF/MANIFEST.MF
  5757 Fri Apr 03 12:21:04 PST 1998 my_helpset.hs
  1345 Wed Feb 18 14:40:16 PST 1998 my_map.jhm
  1478 Wed Feb 18 14:40:16 PST 1998 my_toc.xml
  4678 Thu Mar 12 07:28:54 PST 1998 my_index.xml
  2345 Thu Mar 12 07:28:32 PST 1998 JavaHelpSearch/DOCS
  3456 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/DOCS.TAB
  1457 Fri Mar 13 13:30:06 PST 1998 JavaHelpSearch/OFFSETS
  1465 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/POSITIONS
  1234 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/SCHEMA
  3214 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/TMAP
  3113 Thu Mar 12 07:28:36 PST 1998 topics/topic1/subtopicA/topic.html
   230 Thu Mar 19 11:26:56 PST 1998 topics/topic1/subtopicB/topic.html
  1661 Wed Feb 18 14:40:46 PST 1998 topics/topic2/subtopicA/topic.html
  3181 Wed Feb 18 14:40:46 PST 1998 topics/topic2/subtopicB/topic.html
  1667 Thu Mar 19 11:26:56 PST 1998 topics/topic3/subtopicA/topic.html
  9072 Thu Mar 12 07:28:36 PST 1998 topics/topic3/subtopicB/topic.html
  3673 Thu Mar 19 11:26:56 PST 1998 topics/topic3/subtopicC/topic.html
   551 Fri Mar 13 13:30:12 PST 1998 topics/topic3/subtopicD/topic.html

Extracting Files from JAR Files

Use the x option to extract files from the JAR file: 


C:\> jar -xvf my_help.jar
 extracted: META-INF/MANIFEST.MF
 extracted: my_helpset.hs
 extracted: my_map.jhm
 extracted: my_toc.xml
 extracted: my_index.xml
 extracted: JavaHelpSearch/DOCS
 extracted: JavaHelpSearch/DOCS.TAB
 extracted: JavaHelpSearch/OFFSETS
 extracted: JavaHelpSearch/POSITIONS
 extracted: JavaHelpSearch/SCHEMA
 extracted: JavaHelpSearch/TMAP
 extracted: topics/topic1/subtopicA/topic.html
 extracted: topics/topic1/subtopicB/topic.html
 extracted: topics/topic2/subtopicA/topic.html
 extracted: topics/topic2/subtopicB/topic.html
 extracted: topics/topic3/subtopicA/topic.html
 extracted: topics/topic3/subtopicB/topic.html
 extracted: topics/topic3/subtopicC/topic.html
 extracted: topics/topic3/subtopicD/topic.html
Note that it is not necessary to extract files from the JAR file to use them with the JavaHelp system. The JavaHelp system reads files directly from the JAR file as they are required.

The JAR: Protocol

The JavaTM 2 SDK implements a protocol for referring explicitly to files within JAR files. The syntax of the jar: protocol is: 

    jar:<url>!/{entry}
The jar: protocol can be used to refer to entries within JAR files, the entire JAR file, or a directory as base URLs (JAR directory).

Examples:

An entry within a JAR file: 


    jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class

A JAR file: 


    jar:file://www.foo.com/bar/baz.jar!/

A JAR directory: 


    jar:file://www.foo.com/bar/baz.jar!/COM/foo/

"!/" is referred to as the separator.

For more information, refer to the JavaTM 2 SDK documentation.

See also:

The HelpSet File
The Map File
Table of Contents File
Index File
Creating the Full-Text Search Database