JAR Files

JAR files are commonly used to store a collection of Java files. The files can be source code, bytecode, image files, or anything else a Java program might require. JAR files make it easier to store and deploy the files required by a complicated application. A JAR file can be compressed using the Zip format. Components can be accessed (e.g., Java applications can be executed) directly from JAR files.

JAR files are maintained by the jar utility that is part of the Java SDK. This utility can be used to create, examine, or extract files from a JAR file. The general syntax of the jar utility is

 jar [options] [manifest_name] jar_name [file1,file2,...] 

The manifest name is required only if certain options are used. The files at the end of the jar command syntax are the files that will be stored in the JAR file. The available jar utility options are listed in Table 11.1.

The c , t , and x options are mutually exclusive. You would only use one of them in a given jar command. Using the f option means that the operation will be performed on a file. You would then provide the name of a JAR file. The convention is for JAR file names to end with the .jar extension although this is not mandatory. If you don't use the f option, the files will be read from or written to the standard I/O streams.

Table 11.1. jar Utility Options

C OMMAND	D ESCRIPTION
c	Creates a JAR file.
-C	Allows you to change directories during a JAR creation.
f	Specifies a file to be created, listed, or extracted from. Without this option, the standard input and output streams will be used.
i	Generates index information for the specified JAR file.
m	Includes information from an existing manifest file into the manifest file generated for this JAR file.
M	Indicates that a manifest file will not be included with the JAR file.
t	Lists the contents of an existing JAR file.
u	Updates an existing archive.
v	Generates verbose output.
x	Extracts a specified file from the JAR file. If no files are specified after this command, all the files are extracted.
	Do not use Zip compression.

A JAR file will commonly contain a manifest file describing the contents of the JAR file. The manifest file can be user -specified or can be generated automatically. The manifest file will consist of a series of attribute-value pairs containing information about the JAR file contents. If a manifest file name is specified as part of the jar command, the information in that file will be used to create the manifest file. The system will fill in the blanks of any necessary information not provided in the user-specified manifest file. By default, the manifest file will be placed in a directory named META-INF inside the JAR file.

Be careful when you extract files from a JAR file, because any existing files and directories with the same name or path as the contents of the JAR file will be overwritten. When specifying multiple options, the order of the options generally doesn't matter, but there can't be any spaces between them. The “C option will temporarily change the directory. Immediately after the file following the “C option is accessed, the point of execution will return to the working directory.

To help clear up any lingering confusion about JAR files, let's demonstrate the basic concepts of creating and manipulating JAR files in a series of examples.

Example: Creating a JAR File

Let's create a JAR file using the classes defined in the examples from this chapter. Starting from the working directory that is the root of the Fluids.Gas package hierarchy, we will create the JAR file using the command

 jar cvf species.jar . 

Output ”

 added manifest adding Fluids/(in = 0) (out=0) (deflated 0%) adding Fluids/Gas/(in = 0) (out=0) (deflated 0%) adding Fluids/Gas/IonizedSpecies.class(in=378) (out=268) (deflated 29%) adding Fluids/Gas/IonizedSpecies.java(in=293) (out=165) (deflated 43%) adding Fluids/Gas/Species.class(in=466) (out=303) (deflated 34%) adding Fluids/Gas/Species.java(in=352) (out=159) (deflated 54%) adding SpeciesDriver.class(in=1133) (out=652) (deflated 42%) adding SpeciesDriver.java(in=615) (out=275) (deflated 55%) 

The period at the end of the jar command indicates that all of the files and subdirectories of the current working directory are to be placed in the JAR file. We get the output because we specified v , the verbose option. The output indicates that a manifest was included in the JAR file and lists the files that were added to the file. The size of the files before and after compression is listed.

Example: Viewing the Contents of a JAR File

To view the contents of the previously created species.jar file, we will use the command

 jar tf species.jar 

Output ”

 META-INF/ META-INF/MANIFEST.MF Fluids/ Fluids/Gas/ Fluids/Gas/IonizedSpecies.class Fluids/Gas/IonizedSpecies.java Fluids/Gas/Species.class Fluids/Gas/Species.java SpeciesDriver.class SpeciesDriver.java 

The f option is used to specify the JAR file to be examined. Without the f option you would have to supply the JAR file contents through standard input. We could have also used the v option for verbose output that would include the size of the uncompressed files and the date and time they were last modified.

Example: Extracting Files from a JAR File

To extract the SpeciesDriver.class file from the species.jar file, we would type

 jar xf species.jar SpeciesDriver.class 

When you do this you will see a SpeciesDriver.class file present in your working directory. To really make sure this worked, first delete the existing SpeciesDriver.class file. To extract a file that is stored in a directory, you need to specify the path to the file. For example, to extract the Species.class file, we would type

 jar xf species.jar Fluids/Gas/Species.class 

Note the use of forward slash characters in the expression. Even on Windows machines, you can use forward slashes (rather than the traditional backward slash) to indicate paths if you like. To extract all of the files from the species.jar file, we would type

 jar xf species.jar 

Once again, be careful when extracting files from a JAR file because the extracted files will overwrite any files of the same name and path.

Example: Running an Application from a JAR File

To run an application contained in a JAR file, the manifest file for the JAR must contain a header that tells the Java runtime which class in the JAR file defines the main() method for the application. This header takes the form

 Main-Class: classname 

If we want to run the SpeciesDriver program directly from the species.jar file, we will have to recreate the JAR file attaching a Main-Class header to the manifest file. We first create a text file named species.mf with one line of text, Main-Class: SpeciesDriver . We then recreate the JAR file using the syntax

 jar cmvf species.mf species.jar . 

The information in the species.mf file will be added to the manifest file generated by the system. In this case, the order of the options does matter. The m option must follow the c option and precede the f option. You can now run the SpeciesDriver application using the syntax

 java jar species.jar 

Output ”

 molar mass of atomic nitrogen is 0.0140067 molar mass of diatomic oxygen ion is 0.03199825 charge level of diatomic oxygen ion is 1