3.5. 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, sounds, etc. As we'll see in Chapter 23, a JAR file can 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 understands JAR files and can load class files directly from an archive. So you can pack your application's classes in a JAR file and place it in your CLASSPATH, as described earlier. You can do the equivalent for applets by listing the JAR file in the ARCHIVE attribute of the HTML <applet> tag. Nonclass files (data, images, etc.) contained in your JAR file can also be retrieved from the classpath 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 datafile is an item in a JAR file, an individual file on the classpath, or an applet on a remote server, you can always refer to it in a standard way and let Java's class loader resolve the location.
3.5.1. 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 arbitrary HTML or ASCII containing English words often compress to one-quarter their original size. (On the other hand, image files don't get much smaller when compressed; most of the common image formats have compression built in.)
Compression is not the only advantage that a JAR file has for transporting files over a network. Placing all the classes in a single JAR file enables them to be downloaded in a single transaction. Eliminating the overhead of making HTTP requests is likely to be a big savings, since individual class files tend to be small, and a complex applet could easily require many of them. On the downside, startup time could be increased if a large JAR file must be downloaded over a slow connection before the applet can start up.
Java 5.0 introduces a new 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.
3.5.2. 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:
In these commands, the 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 v 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 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 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
188.8.131.52 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. In Java 1.2 and later, the manifest is by default empty and contains only JAR file version information:
Manifest-Version: 1.0 Created-By: 1.2.1 (Sun Microsystems Inc.)
In Chapter 23, we'll discuss signed JAR files. When you sign a JAR file with a digital signature, digest (checksum) information is added to the manifest for each item in the archive. It looks like this:
Name: com/oreilly/Test.class SHA1-Digest: dF2GZt8G11dXY2p4olzzIc5RjP3= ...
In the case of a signed JAR, the META-INF directory holds digital signature files for items in the archive. In Java 1.1, digest information was always added to the JAR. But since it's really necessary only for signed JAR files, it is omitted by default when you create an archive in Java 1.2 and later.
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. Be careful.
Although these attributes aren't automatically available to the application code, it's easy to retrieve them 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.
184.108.40.206 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:
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 click on the JAR file to launch the application. The interpreter looks for the Main-Class value in the manifest, then loads the named class as the application's initial class.
That's all on JAR files for now. Chapter 23 also picks up where this chapter leaves off in discussing cryptographically "signed" JAR files for trusted applets and application components.
3.5.3. The pack200 Utility
Pack200 is a new archive format introduced with Java 5.0 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 many 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 and web-based applications. We'll talk about these in Chapter 23.
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.