Using the Jar Manifest

Thornton Rose

Published as "Using the Jar Manifest", 3/1/99, Gamelan.com.

After reading my articles on accessing zip and jar files using Java (Accessing Zips and Jars Using Java, Part 1 and Accessing Zips and Jars Using Java, Part 2), a friend and fellow programmer suggested I write about the jar manifest, because documentation on it was sparse at best. So in this article, I'll explain the purpose of the jar manifest and describe its format.

Purpose

The manifest is a special file that contains information about a jar file and its contents. It is stored in the jar file as "META-INF/MANIFEST.MF". The information it contains is used for jar signing, signature verification, class loading, package versioning, and package sealing.

Format

A manifest file is basically a text file. It is divided into sections that contain one or more headers and are separated by blank lines. Headers contain one or more lines that look like this:

Name: Value

Name is the name of the header and can be composed of letters, numbers, "-", and "_", starting with a letter or number. Value is the value of the header and can be text or binary data, which must be encoded as BASE64. Binary data is assumed for digests and signatures.

Header lines can be can be terminated with carriage return (CR), linefeed (LF), or carriage return + linefeed (CRLF), and cannot exceed 72 characters in length, including the terminator. A header can be continued over multiple lines, though, by putting a space at the beginning of each subsequent line, like this:

Foo: 01234566789ABCDEFGHIJKLMNOPQRSTUVWXYZ 01234566789ABCDEFGHIJKLMNOPQRSTUVWXYZ 01234566789ABCDEFGHIJKLMNOPQRSTUVWXYZ 01234566789ABCDEFGHIJKLMNOPQRSTUVWXYZ

At minimum, a manifest must contain one header, the Manifest-Version header, and looks like this:

Manifest-Version: 1.0

All other manifest headers are optional. Here is an example with more headers:

Manifest-Version: 1.0 Main-Class: com.FooInc.FooMaster.Main Name: com/FooInc/FooMaster/Main.class Digest-Algorithms: SHA1 SHA-Digest: TD1GZt8G11dXY2p4olSZPc5Rj64= Name: com/FooInc/FooMaster/FooBean.class Digest-Algorithms: SHA1 SHA-Digest: QD1GZt8W11dXY2p4ilSZPcf5Rj7= Java-Bean: True Name: com/FooInc/FooMaster Specification-Title: FooMaster Specification-Version: 2.1 Specification-Vendor: Foo, Inc. Implementation-Title: com.FooInc.FooMaster Implementation-Version: 2.1 Implementation-Vendor: Foo, Inc. Sealed: True

Preliminary Headers

The first section in a manifest contains the preliminary headers. They are:

Manifest-Version: {version} (required) -- This header is used to specify the version of the manifest format that this manifest is using.
Required-Version: {version} -- This header is used to specify the minimum version of the manifest format that is required for the manifest.
Main-Class: {class} -- This header is used to specify the main class of the application that is bundled in the jar file. Note the specified class must be listed later in the manifest.
Class-Path: {URL list} -- This header is used to specify additional jar files that are needed for the application. The value is a list of URLs to jar files, separated by spaces. The URLs are specified relative to the URL of the jar file.

Here is an example of the preliminary headers:

Manifest-Version: 1.0 Required-Version: 1.0 Class-Path: FooExtras.jar Acme/Beans.jar Main-Class: com.FooInc.FooMaster.Main

Class Headers

The class headers are used to specify information about a class that is contained in the jar. They are:

Name: {class file} (required) -- This header is used to specify the name and path of a class file.
Digest-Algorithms: {list} -- This header is used to specify the algorithms that were used to produce digest values for the named class. This header is added when the jar file is signed.
{x}-Digest: {digest} -- This header is used to specify a specific digest value for the named class. The digest value is the encoded representation of the class file at the time of signing. One of these headers is added for each algorithm specified in the Digest-Algorithms header when the jar file is signed.
Java-Bean: True -- This header is used to indicate that the named class is a JavaBean.

Here is an example of the class headers:

Name: com/FooInc/FooMaster/FooBean.class Digest-Algorithms: SHA1 SHA-Digest: QD1GZt8W11dXY2p4ilSZPcf5Rj7= Java-Bean: True

Package Headers

The package headers are used to specify information about the packages that are contained in the jar file. They are:

Name: {package path}/ (required) -- This header is used to specify the name and path of the package. Note that it must end in "/", which differentiates it from a class header.
Sealed: True -- This header is used to indicate that the package is sealed, which means that all of the classes in the package must be contained in the jar file.
Specification-Title: {title} -- This header is used to specify the title of the named package.
Specification-Version: {version} -- This header is used to specify the version of the named package.
Specification-Vendor: {vendor} -- This header is used to specify the vendor of the named package.
Implementation-Title: {title} -- This header is used to specify the implementation-level title of the named package.
Implementation-Version: {version} -- This header is used to specify the implementation-level version of the named package.
Implementation-Vendor: {vendor} -- This header is used to specify the vendor of the implementation of the named package.

Here is an example of the package headers:

Name: com/FooInc/FooMaster Sealed: True Specification-Title: FooMaster Specification-Version: 2.1 Specification-Vendor: Foo, Inc. Implementation-Title: com.FooInc.FooMaster Implementation-Version: 2.1.37 Implementation-Vendor: The Foo Beanery - A small division of Foo, Inc.

BASE64 Encoding

BASE64 encoding is a method of encoding arbitrary sequences of binary data using only printable ASCII characters. More information on BASE64 can be found in "RFC 1521 - MIME Part 1: Mechanisms for Specifying and Describing the Format of Internet Message Bodies," section 5.2.