Learning Java, 4th Edition

JAR Files

Java Archive (JAR) files are Java’s suitcases. They are the standard and portable way to pack up all the parts of your Java application into a compact bundle for distribution or installation. You can put whatever you want into a JAR file: Java class files, serialized objects, data files, images, audio, etc. A JAR file can also carry one or more digital signatures that attest to its integrity and authenticity. A signature can be attached to the file as a whole or to individual items in the file.

The Java runtime system can load class files directly from an archive in your CLASSPATH, as described earlier. Nonclass files (data, images, etc.) contained in your JAR file can also be retrieved from the classpath by your application using the getResource() method (described in Chapter 12). Using this facility, your code doesn’t have to know whether any resource is in a plain file or a member of a JAR archive. Whether a given class or data file is an item in a JAR file or an individual file on the classpath, you can always refer to it in a standard way and let Java’s class loader resolve the location.

File Compression

Items stored in JAR files are compressed with the standard ZIP file compression. Compression makes downloading classes over a network much faster. A quick survey of the standard Java distribution shows that a typical class file shrinks by about 40 percent when it is compressed. Text files such as HTML or ASCII containing English words often compress to one-tenth their original size or less. (On the other hand, image files don’t normally get smaller when compressed as most common image formats are themselves a compression format.)

Java also has an archive format called Pack200, which is optimized specifically for Java class bytecode and can achieve over four times greater compression of Java classes than ZIP alone. We’ll talk about Pack200 later in this chapter.

The jar Utility

The jar utility provided with the JDK is a simple tool for creating and reading JAR files. Its user interface isn’t particularly friendly. It mimics the Unix tar (tape archive) command. If you’re familiar with tar, you’ll recognize the following incantations:

jar -cvf jarFile path [ path ] [ ... ]

Create jarFile containing path(s).

jar -tvf jarFile [ path ] [ ... ]

List the contents of jarFile, optionally showing just path(s).

jar -xvf jarFile [ path ] [ ... ]

Extract the contents of jarFile, optionally extracting just path(s).

In these commands, the flag letters c, t, and x tell jar whether it is creating an archive, listing an archive’s contents, or extracting files from an archive. The f means that the next argument is the name of the JAR file on which to operate. The optional v flag tells jar to be verbose when displaying information about files. In verbose mode, you get information about file sizes, modification times, and compression ratios.

Subsequent items on the command line (i.e., anything aside from the letters telling jar what to do and the file on which jar should operate) are taken as names of archive items. If you’re creating an archive, the files and directories you list are placed in it. If you’re extracting, only the filenames you list are extracted from the archive. (If you don’t list any files, jar extracts everything in the archive.)

For example, let’s say we have just completed our new game, spaceblaster. All the files associated with the game are in three directories. The Java classes themselves are in the spaceblaster/game directory, spaceblaster/images contains the game’s images, and spaceblaster/docs contains associated game data. We can pack all this in an archive with this command:

    % jar -cvf spaceblaster.jar spaceblaster

Because we requested verbose output, jar tells us what it is doing:

    adding:spaceblaster/ (in=0) (out=0) (stored 0%)
    adding:spaceblaster/game/ (in=0) (out=0) (stored 0%)
    adding:spaceblaster/game/Game.class (in=8035) (out=3936) (deflated 51%)
    adding:spaceblaster/game/Planetoid.class (in=6254) (out=3288) (deflated 47%)
    adding:spaceblaster/game/SpaceShip.class (in=2295) (out=1280) (deflated 44%)
    adding:spaceblaster/images/ (in=0) (out=0) (stored 0%)
    adding:spaceblaster/images/spaceship.gif (in=6174) (out=5936) (deflated 3%)
    adding:spaceblaster/images/planetoid.gif (in=23444) (out=23454) (deflated 0%)
    adding:spaceblaster/docs/ (in=0) (out=0) (stored 0%)
    adding:spaceblaster/docs/help1.html (in=3592) (out=1545) (deflated 56%)
    adding:spaceblaster/docs/help2.html (in=3148) (out=1535) (deflated 51%)

jar creates the file spaceblaster.jar and adds the directory spaceblaster, adding the directories and files within spaceblaster to the archive. In verbose mode, jar reports the savings gained by compressing the files in the archive.

We can unpack the archive with this command:

    % jar -xvf spaceblaster.jar

Likewise, we can extract an individual file or directory with:

    % jar -xvf spaceblaster.jar filename

But, of course, you normally don’t have to unpack a JAR file to use its contents; Java tools know how to extract files from archives automatically. We can list the contents of our JAR with the command:

    % jar -tvf spaceblaster.jar

Here’s the output; it lists all the files, their sizes, and their creation times:

    0 Thu May 15 12:18:54 PDT 2003 META-INF/
      1074 Thu May 15 12:18:54 PDT 2003 META-INF/MANIFEST.MF
         0 Thu May 15 12:09:24 PDT 2003 spaceblaster/
         0 Thu May 15 11:59:32 PDT 2003 spaceblaster/game/
      8035 Thu May 15 12:14:08 PDT 2003 spaceblaster/game/Game.class
      6254 Thu May 15 12:15:18 PDT 2003 spaceblaster/game/Planetoid.class
      2295 Thu May 15 12:15:26 PDT 2003 spaceblaster/game/SpaceShip.class
         0 Thu May 15 12:17:00 PDT 2003 spaceblaster/images/
      6174 Thu May 15 12:16:54 PDT 2003 spaceblaster/images/spaceship.gif
     23444 Thu May 15 12:16:58 PDT 2003 spaceblaster/images/planetoid.gif
         0 Thu May 15 12:10:02 PDT 2003 spaceblaster/docs/
      3592 Thu May 15 12:10:16 PDT 2003 spaceblaster/docs/help1.html
      3148 Thu May 15 12:10:02 PDT 2003 spaceblaster/docs/help2.html

JAR manifests

Note that the jar command automatically adds a directory called META-INF to our archive. The META-INF directory holds files describing the contents of the JAR file. It always contains at least one file: MANIFEST.MF. The MANIFEST.MF file can contain a “packing list” naming the files in the archive along with a user-definable set of attributes for each entry.

The manifest is a text file containing a set of lines in the form keyword: value. The manifest is, by default, empty and contains only JAR file version information:

Manifest-Version: 1.0
Created-By: 1.7.0_07 (Oracle Corporation)

It is also possible to sign JAR files with a digital signature. When you do this, digest (checksum) information is added to the manifest for each archived item (as shown next) and the META-INF directory holds digital signature files for items in the archive.

    Name: com/oreilly/Test.class
    SHA1-Digest: dF2GZt8G11dXY2p4olzzIc5RjP3=
    ...

You can add your own information to the manifest descriptions by specifying your own supplemental, manifest file when you create the archive. This is one possible place to store other simple kinds of attribute information about the files in the archive, perhaps version or authorship information.

For example, we can create a file with the following keyword: value lines:

    Name: spaceblaster/images/planetoid.gif
    RevisionNumber: 42.7
    Artist-Temperament: moody

To add this information to the manifest in our archive, place it in a file called myManifest.mf and give the following jar command:

    % jar -cvmf myManifest.mf spaceblaster.jar spaceblaster

We included an additional option, m, which specifies that jar should read additional manifest information from the file given on the command line. How does jar know which file is which? Because m is before f, it expects to find the manifest information before the name of the JAR file it will create. If you think that’s awkward, you’re right; get the names in the wrong order, and jar does the wrong thing.

An application can get this manifest information from a JAR file using the java.util.jar.Manifest class.

We’ll see more examples of adding information to the JAR manifest in Chapter 22. The JavaBeans APIs use manifest information to designate which classes are “beans” using a Java-Bean attribute. This information is used by IDEs that work with JavaBeans.

Making a JAR file runnable

Aside from attributes, you can put a few special values in the manifest file. One of these, Main-Class, allows you to specify the class containing the primary main() method for an application contained in the JAR:

    Main-Class: com.oreilly.Game

If you add this to your JAR file manifest (using the m option described earlier), you can run the application directly from the JAR:

    % java -jar spaceblaster.jar

More importantly, under Mac OS X, Windows, and other GUI environments, you can simply double-click on the JAR file to launch the application. The interpreter looks for the Main-Class value in the manifest, then loads the designated class as the application’s startup class.

The pack200 Utility

Pack200 is an archive format that is optimized for storing compiled Java class files. Pack200 is not a new form of compression, but rather a super-efficient layout for class information that eliminates many types of waste and redundancy across related classes. It is effectively a bulk class-file format that deconstructs many classes and reassembles their parts efficiently into one catalog. This then allows a standard compression format like ZIP to work at maximum efficiency on the archive, achieving four or more times greater compression. The Java runtime does not understand the Pack200 format, so you cannot place archives of this type into the classpath. Instead, it is mainly an intermediate format that is very useful for transferring application JARs over the network for applets or other kinds of web-based applications.

You can convert a JAR to and from Pack200 format with the pack200 and unpack200 commands supplied with the JDK.

For example, to convert foo.jar to foo.pack.gz, use the pack200 command:

    % pack200 foo.pack.gz foo.jar

To convert foo.pack.gz to foo.jar:

    % unpack200 foo.pack.gz foo.jar

Note that the Pack200 process completely tears down and reconstructs your classes at the class level, so the resulting foo.jar file will not be byte-for-byte the same as the original.