7.2 JAR Files

Virtually all delivery mechanisms for Java applications depend on packaging the .class files created from your .java source files into one or more Java Archive (JAR) files. Think of a JAR file as a special sort of ZIP archive, with a very specific set of expected characteristics and layout. You can use the jar tool included with the JDK, an Ant task, or the specific capabilities of your preferred Java development environment to create a JAR file.

The standard way to create a JAR file, of course, is to use the command-line jar command included with Mac OS X's JDK. Open the Terminal, type jar, and a list of options will appear:

Usage: jar {ctxu}[vfm0M] [jar-file] [manifest-file] [-C dir] files ...
    -c  create new archive
    -t  list table of contents for archive
    -x  extract named (or all) files from archive
    -u  update existing archive
    -v  generate verbose output on standard output
    -f  specify archive file name
    -m  include manifest information from specified manifest file
    -0  store only; use no ZIP compression
    -M  do not create a manifest file for the entries
    -i  generate index information for the specified jar files
    -C  change to the specified directory and include the following file
If any file is a directory then it is processed recursively.
The manifest file name and the archive file name needs to be specified
in the same order the 'm' and 'f' flags are specified.

Example 1: to archive two class files into an archive called classes.jar: 
       jar cvf classes.jar Foo.class Bar.class 
Example 2: use an existing manifest file 'mymanifest' and archive all the
           files in the foo/ directory into 'classes.jar': 
       jar cvfm classes.jar mymanifest -C foo/ .

7.2.1 Creating a JAR File

If you work with the source for the SimpleEdit application presented in Chapter 4, you should have it organized as shown in Figure 7-1.

Figure 7-1. SimpleEdit source tree

Let's package the core SimpleEdit files into a single JAR, which you will make double-clickable (and therefore executable by an end user). Suppose that you have compiled the source files already, either using javac, Ant, or an IDE.

To make the JAR double-clickable, you'll need a manifest file to specify the main class in the JAR. Create a text file called manifest.mf with contents as shown in Example 7-1. Save this file inside the src directory of your application folder. Note that this manifest.mf file is very particular about the carriage return sequence used (see Chapter 6 for more information about carriage returns). You may wish to use the Terminal's more command to display your manifest.mf file?if you see any ^M characters in it using that command or when viewing the file with vi or emacs, you've got a problem.

Example 7-1. A simple manifest file

This scenario is pretty self-explanatory: the manifest file will instruct Java on the class to launch when the JAR it is included within is double-clicked. You can specify any Java class as the main class, but make sure that it's a class that actually has a main( ) method, or you'll encounter errors when distributing your application.

Open the Terminal and use the cd and pwd commands to navigate to the src directory. In this directory, type the JAR command as shown:

jar cvfm SimpleEdit.jar manifest.mf ./com/wiverson/macosbook/*.class  

After entering this command and pressing return, you should see something similar to the following output:

added manifest
adding: com/wiverson/macosbook/SimpleApplet$1.class(in = 770) (out= 
425)(deflated 44%)
adding: com/wiverson/macosbook/SimpleApplet.class(in = 909) (out= 
527)(deflated 42%)
adding: com/wiverson/macosbook/SimpleEdit$1.class(in = 1187) (out= 
625)(deflated 47%)
adding: com/wiverson/macosbook/SimpleEdit.class(in = 11062) (out= 
5521)(deflated 50%)
adding: com/wiverson/macosbook/SimpleEditPlugin.class(in = 323) (out= 
206)(deflated 36%)

... omitted for space...

adding: com/wiverson/macosbook/plugin/QuitConfirmJDialog.class(in = 4367) 
(out= 1917)(deflated 56%)
adding: com/wiverson/macosbook/plugin/SystemPropsPlugin.class(in = 1827) 
(out= 892)(deflated 51%)

7.2.2 Launching the JAR File

If all goes well, double-clicking on the generated JAR file will automatically launch the SimpleEdit application. This JAR file can be moved to other platforms, and users of JDK 1.2 or later should be able to move it as well.

Even if you distribute the JAR file by using another mechanism (for example, as part of an application bundle, delivered as a web applet, or as a Web Start application), it's often useful to deliver the JAR file with a Main-Class specified in a manifest file for development and testing purposes.

Applications launched as double-clickable JARs will use the most recent Mac OS X JDK installed (either JDK 1.3.1 or JDK 1.4.1). If you distribute your application in this manner, you should therefore test it on both JVMs. If you wish to force JDK 1.3.1 or require JDK 1.4.1, you should use an application bundle, as described in the next section.