This topic describes how JAR files are used in the JavaHelp system.
jar commandAfter 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.
The following sections refer to this sample help hierarchy:
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.
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:
C:\> cd ...\help (where "..." is the path above the \help folder)C:...\help> jar -cvf my_help.jar *
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.
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
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 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: