Java Tools for Development and Testing:
jar Files (Executable and Non-Executable)

What is the jar utility and what can it do for you?

Java platforms provide a utility called jar (for Java ARchive), which gives us another way to "package" classes in a single entity and make them available to clients. In this context, one can view the jar utility simply as an alternate to other popular programs such as pkzip or WinZip. However, it is also possible for the java interpreter to read class information directly from a jar file.

Also, in the context of Microsoft's new C# programming language an assembly is defined to be a unit of deployment and execution which is self-describing via a manifest. To which one might respond with the question, "OK, but so is a jar file, isn't it?" Since the answer appears to be yes, this may be one more piece of evidence of the "convergence of technologies".

Storing files in a jar file, viewing them, and retrieving them

The following command will put the two class files Foo.class and Bar.class into the Java archive file foobar.jar:

jar cvf foobar.jar Foo.class Bar.class

The following command will show you what's in foobar.jar:

jar tvf foobar.jar

The following command will extract the files in foobar.jar:

jar xvf foobar.jar

Running a main program that accesses classes stored in a jar file

Suppose we have a program that consists of the the three classes Foo.class, Bar.class and FooBarMain.class, and we have stored the auxiliary class files Foo.class and Bar.class in the file foobar.jar. Then we can run the program with the following command:

java -classpath .;foobar.jar FooBarMain

The -classpath option on the java command line gives the explicit locations of all the files needed to run the program. The dot, or period (.), refers to the current directory, where the class containing the main() that we want to run is located, and the other two classes are in the jar file, which is also in the current directory.

It is important to remember that for the java interpreter to access the files in foobar.jar you must have as one component of your classpath the path to foobar.jar (of course) but also the name of the file itself must be included at the end of that path. [Contrast this with the situation for a package, where the classpath need only contain the path(s) to the package file(s) but not the name(s) of any specific file(s).]

Running programs (even "cross-platform") from a single jar file

A very useful feature of Java is that you can place all the files for your program in a single jar file and then run the program directly from that jar file, and (here's the really wonderful thing) use that same jar file on different platforms. For example, you can build the jar file under Linux, then simply transfer that file to Windows and run it there, either from the command line in a console window or, if it is a GUI application and no console window is desired, simply by double-clicking on it in Windows Explorer.

If we wish to do this, then one of the files in the jar file must be something called a "manifest" file which, in its simplest form, tells the java interpreter which of the class files in the jar file is the one to use to start the program running (i.e., the class file whose name would be supplied at the command line if you were running the program in the "normal" way).

For example, suppose we have a complex "Hello World!" program with several class files, all of which start with 'H'. Here are the two commands that we would need, the first to create, and the second to run, the jar file containing the program:

jar cvmf manifest.mf hello.jar H*class
java -jar hello.jar

There are two important things to note:

• In the first of the above two commands, the manifest file and the jar file must appear on the command line in the same order as the 'm' and the 'f' in the 'mf' of the command-line options). In this example we used the wildcard charcter * to get all the class files necessary for the jar file, but the individual files required can also be listed, as can a combination of wildcard designations and individual files.
• Assuming the class file containing the main function driver for this program is called HelloMain.class, then the contents of the manifest file manifest.mf must be (in this case) the single line:

  Main-Class: HelloMain
  

  and to ensure that the manifest file is read properly you should ensure that you have entered a newline character at the end of the above line (by pressing Enter in your editor after you have entered the line and before saving the file).

A Simpler Way to Create an Executable Jar File

An alternative to the above procedure for creating an executable jar file, which eliminates the need for a manifest file, is the following:

> jar cvfe JarFile.jar MainClass MainClass.class OtherClass1.class OtherClass2.class (and so on)

Some Additional Useful Features

• Sometimes creating a jar file, particularly an executable jar file, can involve typing in a very long command at the command-line prompt. You can avoid this by putting everything except the jar command itself into a text file (over several lines if you like) and then create the jar file with this command (assuming you've named the file jar.txt):

  jar @jar.txt
  

• If you have some classes that you habitually want to use frequently when you create an executable jar file, you can put those classes in a subdirectory somewhere and then, as one of the jar command qualifiers in your jar.txt file (mentioned in the previous point) you can have something of this form

  -C path_to_subdirectory_containing_the_class_you_want/ClassName.class
  

  if you want to include just one particular class in your jar file, or something of this form

  -C path_to_subdirectory_containing_classes_all_of_which_you_want .
  

  if you want to include all of the classes from a particular subdirectory in your jar file (and yes, that is a . and not a *).
• If you are producing a non-executable jar file and don't want the default manifest to be included, you can use the M qualifier with the jar command to achieve this.
• If you want to update an existing jar file by replacing one of the files it contains with a newever version, you can do that by "updating" the file with this syntax:

  jar uf jarfile.jar updated_file
  

List of All Topics