This is an old revision of the document!
Table of Contents
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-fileinput-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 .