This is an old revision of the document!


The Java Archive Tool (jar)

Overview

The jar tool can be used to bundle multiple files into a single file. JAR files typiclaly contain the class files and resources (e.g., images) required by an application.

Resources in a JAR file can be accessed from the application using a java.net.URL object created using the java.lang.Class#getResource(java.lang.String) method or the java.lang.Class#getResourceAsStream(java.lang.String) method or the in the Class class.

Viewing the Contents of a JAR File

To view the contents of a JAR file:

jar tf jar-file

Creating a JAR File

To create a JAR file:

jar cf jar-file input-files

where input-files can include .class files, packages, and resources of various kinds.

Creating an Executable JAR File

An “executable JAR” file can be executed using the java tool with the -jar switch or, if the associations are set properly, by “clicking” on it.

You can create an executable JAR file by including a manifest that includes a Main-Class: directive. For more information, see the tutorial .

Permissions and Executable .jar Files

Depending on your operating system, you may need to change the permissions of the executable .jar file (i.e., provide permission to execute). In most OSs this can be done from the command line (using chmod) or from the GUI (in a variety of different ways).

You may also need to set the default manner in which it is “opened” (i.e., instruct the OS to used the Java runtime). This is sometimes also called the files “association” or “default program”. From the command line: in MS Windows you can use assoc, is OS X you can edit ~/Library/Preferences/com.apple.launchservices.plist, and in Linux you can edit /usr/share/applications/defaults.list From the GUI: in MS Windows you can click on Start+Default Programs, in OS X you can right-click on the file and use File+Get Info, and in Linux you can right-click and select Properties

Testing an Executable .jar File

If you just click/double-click on an executable .jar file and the code throws an exception you (typically) won't see it. Hence, when testing it is often useful to run the application from the command line. To do so, open a command shell, change the working directory to the directory that contains the .jar file, and then execute the application as follows:

java -jar filename.jar

Using Resources in a .jar File

You may want to include files other than .class files in a .jar file (e.g., images, configuration files, input files). Such files are often called resources. To refer to a resource in a .jar file you should use a URL object (from the java.net package).

The easiest way to get the appropriate URL object is to use a Class object. For example, if you want to get the URL for a resource named logo.png that is in the resources directory under the directory containing the class of the object referred to by this then you would do the following:

URL url = this.getClass().getResource("resources/logo.png").

You could then load it as follows:

ImageIcon icon = new ImageIcon(url);

You can get an InputStream for a resource in a similar fashion. For example:

InputStream is = this.getClass().getResource("resources/config.txt").
BufferedReader in = new BufferedReader(new InputStreamReader(is));
String   line = in.readLine();

This technique uses the ClassLoader infrastructure to retrieve resources from the .jar file. So, it is very important that you understand the relative locations of the resource and the object that you call getClass() on. A leading / will start at the root of the directory tree, but you still must understand where in the .jar file is the root.

Changing the Icon of Executable .jar Files

By default, executable .jar files use the Java icon.

To change the icon in OS X, copy the icon you want to use (using Commmand+C), right-click on the .jar file, pull down to Get Info, click on the icon in the upper-left corner of the dialog box, and paste the icon (using +V).

To change the icon in many Linux distributions, right-click on the .jar file, pull down to Properties, click on the “Basic” tab, and then click-and-drag the icon you want to use to the icon in the upper-left corner of the dialog box.

In MS-Windows you can't change the icon of the .jar file directly. However, you can create a shortcut and change it's icon. To do so, right-click on the .jar file and pull down to Create shortuct. Then, right-click on the shortcut, pull down to Properties, click on the “Shortcut” tab, click on Change Icon…, navigate to the .ico file, click on OK, and click on OK.

For More Information

The jar tool is very powerful and has a number of capabilities that are not discussed here. For more information, see the tutorial .