JAR (file format)


A JAR is a package file format typically used to aggregate many Java class files and associated metadata and resources into one file for distribution.
JAR files are archive files that include a Java-specific manifest file. They are built on the ZIP format and typically have a .jar file extension.

Design

A JAR file allows Java runtimes to efficiently deploy an entire application, including its classes and their associated resources, in a single request. JAR file elements may be compressed, shortening download times.
A JAR file may contain a manifest file, that is located at META-INF/MANIFEST.MF. The entries in the manifest file describe how to use the JAR file. For instance, a Classpath entry can be used to specify other JAR files to load with the JAR.

Extraction

The contents of a JAR file may be extracted using any standard decompression software, or the jar command line utility: "jar -xf foo.jar".

Security

Developers can digitally sign JAR files. In that case, the signature information becomes part of the embedded manifest file. The JAR itself is not signed, but instead every file inside the archive is listed along with its checksum; it is these checksums that are signed. Multiple entities may sign the JAR file, changing the JAR file itself with each signing, although the signed files themselves remain valid. When the Java runtime loads signed JAR files, it can validate the signatures and refuse to load classes that do not match the signature. It can also support 'sealed' packages, in which the Classloader will only permit Java classes to be loaded into the same package if they are all signed by the same entities. This prevents malicious code from being inserted into an existing package, and so gaining access to package-scoped classes and data.
The content of JAR files may be obfuscated to make reverse engineering more difficult.

Executable JAR files

An executable Java program can be packaged in a JAR file, along with any libraries the program uses. Executable JAR files have the manifest specifying the entry point class with Main-Class: myPrograms.MyClass and an explicit Class-Path. Some operating systems can run these directly when clicked. The typical invocation is java -jar foo.jar from a command line.
Native launchers can be created on most platforms. For instance, Microsoft Windows users who prefer having Windows EXE files can use tools such as JSmooth, Launch4J, WinRun4J or Nullsoft Scriptable Install System to wrap single JAR files into executables.

Manifest

A manifest file is a metadata file contained within a JAR. It defines extension and package-related data. It contains name-value pairs organized in sections. If a JAR file is intended to be used as an executable file, the manifest file specifies the main class of the application. The manifest file is named MANIFEST.MF. The manifest directory has to be the first entry of the compressed archive.

Specifications

The manifest appears at the canonical location META-INF/MANIFEST.MF. There can be only one manifest file in an archive and it must be at that location.
The content of the manifest file in a JAR file created with version 1.0 of the Java Development Kit is the following.
Manifest-Version: 1.0
The name is separated from its value by a colon. The default manifest shows that it conforms to version 1.0 of the manifest specification.
The manifest can contain information about the other files that are packaged in the archive. Manifest contents depend on the intended use for the JAR file. The default manifest file makes no assumptions about what information it should record about other files, so its single line contains data only about itself. It should be encoded in UTF-8.

Special-Purpose Manifest Headers

JAR files created only for the purpose of archiving do not use the MANIFEST.MF file.
Most uses of JAR files go beyond simple archiving and compression and require special information in the manifest file.

Applications

If an application is contained in a JAR file, the Java Virtual Machine needs to know the application's entry point. An entry point is any class with a public static void main method. This information is provided in the Main-Class header, which has the general form:
Main-Class: com.example.MyClassName
In this example com.example.MyClassName.main executes at application launch.

Package Sealing

Optionally, a package within a JAR file can be sealed, which means that all classes defined in that package are archived in the same JAR file. A package might be sealed to ensure version consistency among the classes in the software or as a security measure.
To seal a package, a Name entry needs to appear, followed by a Sealed header, such as:

Name: myCompany/myPackage/
Sealed: true

The Name header's value is the package's relative pathname. Note that it ends with a '/' to distinguish it from a filename. Any headers following a Name header, without any intervening blank lines, apply to the file or package specified in the Name header. In the above example, because the Sealed header occurs after the Name: myCompany/myPackage header with no intervening blank lines, the Sealed header applies to the package myCompany/myPackage.

Package Versioning

Several manifest headers hold versioning information. One set of headers can be assigned to each package. The versioning headers appear directly beneath the Name header for the package. This example shows all the versioning headers:

Name: java/util/
Specification-Title: "Java Utility Classes"
Specification-Version: "1.2"
Specification-Vendor: "Sun Microsystems, Inc.".
Implementation-Title: "java.util"
Implementation-Version: "build57"
Implementation-Vendor: "Sun Microsystems, Inc."

Dependencies

The MANIFEST.MF file can be used to specify all the classes that must be loaded for an application to be able to run.
Note that Class-Path entries are delimited with spaces, not with the system path delimiter:

Class-Path:. pkg1.jar path/to/pkg2.jar

Apache Ant Zip/JAR support

The Apache Ant build tool has its own package to read and write Zip and JAR archives, including support for Unix filesystem extensions. The org.apache.tools.zip package is released under the Apache Software Foundation license and is designed to be usable outside Ant.

Related formats

Several related file formats build on the JAR format: