Java Basics: JAR Files
JAR files are Java’s way of distributing libraries and executable programs. JAR is short for Java ARchive . JARs are just ZIP files with a .jar extension and a special directory structure. They can contain the programs or library’s classes as well as any other files they may need. A special file called /META-INF/MANIFEST.MF is often required to be in the archive and contains information about the JAR content, such as the name of the main class and its dependencies.
- you want to bundle a Java application’s files for distribution, or
- you need to deploy your code at a place where you need it as a JAR, or
- you need to sign your code, for example to execute it in a web browser or on a cell phone
Java supports JARs since version 1.1 (in other words, practically forever).
Creating JARs
JARs are just ZIP files with a .jar extension and a special directory structure. Meta information is in a directory called META-INF , with the manifest file /META-INF/MANIFEST.MF being the most important file.
Beside META-INF , you add any file you want to the JAR file. Classes must be put into the usual Java directory structure.
This is an example layout for a JAR file, with a manifest file and two classes «com.jarfiller.example.MainClass» and «com.jarfiller.example.Helper»:
Content of jarfiller-example.jar META-INF/ (directory) META-INF/MANIFEST.MF (Manifest file) com/ (directory) com/jarfiller/ (directory) com/jarfiller/example/ (directory) com/jarfiller/example/MainClass.class (Java class) com/jarfiller/example/Helper.class (Java class)
The manifest file ( /META-INF/MANIFEST.MF ) describes the content of the JAR file. It is not required, but often automatically added by JAR tools.
The following manifest declares only a main class:
Manifest-Version: 1.0 Main-Class: com.jarfiller.example.MainClass
Rules for Manifest Files
- a manifest contains key/value pairs (called attributes ), one per line
- attribute syntax: attribute name, directly followed by a colon (‘:’), a single space and the value
- values may span several lines. Each additional line must start with one space.
- no additional whitespace allowed (more)
- no empty lines allowed in the main section (there can be additional sections, separated by empty lines)
Common Attributes
| Name | Description | Example |
|---|---|---|
| Manifest-Version | File format version of the manifest, always ‘1.0’, required | 1.0 |
| Main-Class | Name of the class containing the main method in executable JARs | my.package.MainClass |
| Class-Path | Space-separated list of relative paths to JAR files and directories for the classpath | lib/util.jar lib/helper.jar drivers/ |
| Sealed | if «true», then packages are sealed. Otherwise «false». | true |
| Created-By | Creator of the JAR; automatically added by the jar tool; not important | 1.6.0_12 (Sun Microsystems Inc.) |
| Implementation-Title | Name of the program/library contained in the JAR | My Super App |
| Implementation-Version | Version of the program/library contained in the JAR | 1.0d |
| Implementation-Vendor | Vendor of the program/library contained in the JAR | Super Soft Inc. |
| Specification-Title | Name of the specification the library implements (more) | Super API |
| Specification-Version | Version of the specification | 1.0 |
| Specification-Vendor | Vendor of the specification | Super Group |
Beside those common attributes, there are many special purpose attributes. For example, if you package a Java Applet or a OSGi Bundle in a JAR, there are specific (and often required) attributes for them. For a simple library or executable JAR they are not needed though.
Example
Manifest-Version: 1.0 Created-By: 1.6.0_12 (Sun Microsystems Inc.) Class-Path: lib/common.jar lib/helpers.jar lib/util-impl.jar stdlib/j2ee.jar stdlib/mail.jar drivers/mysql-jdbc.jar drivers/jag-ext.jar extensions/ Implementation-Title: Jarfiller Test App Implementation-Version: 0.1 Implementation-Vendor: jarfiller.org
The JDK ships with a command line tool called jar to create, view and unpack JAR files. On Windows, use it like this:
C:\Users\tim>set PATH=c:\Program Files\Java\jdk1.6.0_13\bin;%PATH% C:\Users\tim>jar Usage: jar [vfm0Me] [jar-file] [manifest-file] [entry-point] [-C dir] files . .
To create a JAR file from your compiled classes, enter:
C:\Users\tim>jar cvf tmp/jarfiller-example.jar -C workspace/JarTest/bin . added manifest adding: com/(in = 0) (out= 0)(stored 0%) adding: com/jarfiller/(in = 0) (out= 0)(stored 0%) adding: com/jarfiller/example/(in = 0) (out= 0)(stored 0%) adding: com/jarfiller/example/Helper.class(in = 287) (out= 212)(deflated 26%) adding: com/jarfiller/example/MainClass.class(in = 569) (out= 351)(deflated 38%)
To specify a manifest file, either put it into the base directory (would be workspace/JarTest/bin/META-INF/MANIFEST.MF ), or use the ‘m’ parameter:
C:\Users\tim>jar cvfm tmp/jarfiller-example.jar workspace/JarTest/manifest/MANIFEST.MF ^ -C workspace/JarTest/bin . added manifest adding: com/(in = 0) (out= 0)(stored 0%) adding: com/jarfiller/(in = 0) (out= 0)(stored 0%) adding: com/jarfiller/example/(in = 0) (out= 0)(stored 0%) adding: com/jarfiller/example/Helper.class(in = 287) (out= 212)(deflated 26%) adding: com/jarfiller/example/Helper.java(in = 56) (out= 58)(deflated -3%) adding: com/jarfiller/example/MainClass.class(in = 569) (out= 351)(deflated 38%) adding: com/jarfiller/example/MainClass.java(in = 147) (out= 127)(deflated 13%)
How to.
Usually the .jar file extension is associated with the Java runtime. That means that just by double-clicking an executable JAR the application should start. Unfortunately executable JARs have the same extension as other JARs, such as libraries. So you can’t tell which JAR is executable, unless you look at its MANIFEST.MF file.
On the command line, you start an executable JAR by running java with the -jar option:
JARs are only ZIP files with a funny name, so you can view and unpack them with any ZIP tool. You may have to change its extension to ‘.zip’ before, if the tool does not recognize the JAR otherwise.
The jar tool shipped with the JDK also allows you to view and extract them on the command line. Use the ‘t’ command to view the content:
C:\Users\tim>jar tvf tmp/jarfiller-example.jar 0 Wed Jan 20 21:34:06 CET 2010 META-INF/ 116 Wed Jan 20 21:34:06 CET 2010 META-INF/MANIFEST.MF 0 Sat Jan 16 16:11:50 CET 2010 com/ 0 Sat Jan 16 16:11:50 CET 2010 com/jarfiller/ 0 Sun Jan 17 15:34:08 CET 2010 com/jarfiller/example/ 287 Sun Jan 17 15:46:18 CET 2010 com/jarfiller/example/Helper.class 56 Sun Jan 17 15:46:18 CET 2010 com/jarfiller/example/Helper.java 569 Sat Jan 16 16:14:00 CET 2010 com/jarfiller/example/MainClass.class 147 Sat Jan 16 16:13:58 CET 2010 com/jarfiller/example/MainClass.java
Unpack a JAR with the ‘x’ command:
C:\Users\tim>cd tmp C:\Users\tim\tmp>jar xvf tmp/jarfiller-example.jar created: META-INF/ inflated: META-INF/MANIFEST.MF created: com/ created: com/jarfiller/ created: com/jarfiller/example/ inflated: com/jarfiller/example/Helper.class inflated: com/jarfiller/example/Helper.java inflated: com/jarfiller/example/MainClass.class inflated: com/jarfiller/example/MainClass.java
Most JARs, no matter whether they contain an executable program or a library, require other libraries to run. Those dependencies are usually contained in JARs as well. So how can you make sure that your JAR has all required JARs in its CLASSPATH? There are three common solutions for executable JARs.
Solution 1: Using the Class-Path Attribute
The Class-Path attribute of the manifest file allows you to state a list of JARs that the Java runtime should put into its classpath. So basically your program consists of several JARs, one executable for the program itself and one JAR for each library.
This example shows a manifest file with several dependencies:
Manifest-Version: 1.0 Main-Class: com.jarfiller.example.MainClass Class-Path: log4j.jar mail.jar
Note that your IDE may be able to create such a manifest and package your libraries automatically. For example, Eclipse can do this since version 3.5 (export your project as ‘Runnable JAR file’ and select the appropriate option).
Solution 2: Unpack Library JARs into a Single JAR
A nifty solution to the problem is to unpack all JARs you depend on and put them all into a single JAR. This works most of the time, but with some JARs, such as Service Providers, it won’t (more).
There are several tools that allow you to do this to various extends (e.g. they may not merge the manifests of the JARs correctly). Recent Eclipse versions can repack executable JARs. Just export the project into a ‘Runnable JAR file’ and select the right option.
Ant also allows you to unpack JARs into a single JAR using the jar task.
Solution 3: Call java with all JARs in the CLASSPATH
Another common solution is to write a script or batch file that puts all JARs into the classpath and then starts the application. This also allows you to add other arguments to the Java runtime (such as an increased heap) and state the main class (so you don’t need a special manifest). Then you start the application like this:
C:\Users\tim\tmp>java -cp jarfiller-example.jar;log4j.jar;mail.jar com.jarfiller.example.MainClass
Dependencies for Library
Most libraries also depend on other libraries. Theoretically you could apply Solution 1 or Solution 2 to a library. This would be rather unusual though. Common practice is to state your dependencies somewhere in the documentation (or just have a directory containing dependencies) and let the library’s user take care of putting them into the classpath. Do not apply the solutions above to libraries.
The main reason is that the you (or, rather, the library’s user) needs to be sure to have every library only once in the classpath. With Solution 1, two JARs could depend on the same library, but use different names for it, and you end up with including the library twice. With Solution 2, several JARs could contain the same library. Both solutions get especially messy when different versions of the same library are involved.
Some JARs need to be signed, for example a JAR containing a Java Applet that requires certain privileges. Signing means that a digital signature is used to authenticate the author of the JAR. How exactly digital signatures work is out of the scope of this document (read the Wikipedia article as starting point), but what it effectively does is let somebody certify your identity. Idealy, but not necessarily, this somebody is a trusted certificate authority.
A digital signature has two main components. The first one is your private key that represents you. And then you need a certificate by somebody who certifies that you are who you claim to be. In the simplest case, you can create the certificate yourself. This is called a self-signed certificate. Obviously it is not very trustworthy, because anybody can certificate himself to be anybody. But for testing this is usually the easiest solution. Beside the lack of security, the major disadvantage of self-signed certificates is that the user will see a lot of warnings when installing your software, and may even be unable to install it without having system administrator privileges.
If you want to publish your software for the public, you should get a real certificate from a trusted certificate authority. The next how-to will help you get this, but for now, I show you how to create a self-signed certificate.
To sign a JAR, the first thing you need is the private key. Only you should own this key, as anybody who gets hold of it can claim to be you. Java stores keys in a file called keystore. You must assign each key in the keystore a name, called «alias» by Java (more). The main tool to manage keystores is a command line tool called keytool which ships with the JDK.
This is how to create a new key, either adding it to an existing keystore or creating a new one. The key will automatically be self-signed:
C:\Users\tim\tmp>keytool -genkey -keyalg RSA -alias myFirstKey -keystore myKeystore -validity 360
The command will ask you a couple of questions. First you can protect your keystore with a password, if you create a new one. You should do this if you plan to publish software with the keys in the keystore. Then it will ask you for your name, organization and location. This information is what will be shown to the user and possibly be certified by the certificate authority, so be careful to enter the right values.
Now that you have a (self-signed) key, you can easily sign your JAR with the jarsigner tool:
C:\Users\tim\tmp>jarsigner.exe -keystore myKeystore -verbose jarfiller-example.jar myKey