We know this was another whirlwind tour with several bits of code that might not make sense yet, like why is CENTER in all caps? Or why is the class name JLabel used before our center alignment? Hopefully, typing along, probably making a few small mistakes, correcting them, and seeing the results makes you want to know more. We just want to make sure you have the tools needed to continue playing along as you go throughout the rest of this book. Like so many other skills, programming benefits from doing in addition to reading!
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=
...
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.
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
Some GUI environments used to support double-clicking 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. This feature seems to be in flux and is not supported on all operating systems, so you may need to investigate other Java application distribution options if you are creating an app you want to share with others.