## JAR Files

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

- Using JAR files
- The `jar` command
- Creating JAR files
- Listing JAR files
- Extracting files from JAR files
- The JAR protocol

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

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 J2SE.

### 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 called the separator.

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

See also:

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