Java Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE

1. Introduction

A Java Archive (JAR) is described by its manifest file. This article explores its many capabilities, including adding attribution, making the JAR executable, and embedding versioning information.

Let's begin, though, with a quick review of what a manifest file is.

2. The Manifest File

The manifest file is named MANIFEST.MF and is located under the META-INF directory in the JAR. It's simply a list of key and value pairs, called headers or attributes, grouped into sections.

These headers supply metadata that help us describe aspects of our JAR such as the versions of packages, what application class to execute, the classpath, signature material and much more.

3. Adding a Manifest File

3.1. The Default Manifest

A manifest file is added automatically whenever we create a JAR.

For example, if we build a JAR in OpenJDK 11:

jar cf MyJar.jar classes/

It produces a very simple manifest file:

Manifest-Version: 1.0
Created-By: 11.0.3 (AdoptOpenJDK)

3.2. A Custom Manifest

Or, we can specify our own manifest file.

For example, let's say that we have a custom manifest file called manifest.txt:

Built-By: baeldung

We can include this file and jar will merge it with the default manifest file when we use the m option:

jar cfm MyJar.jar manifest.txt classes/

Then, the resulting manifest file is:

Manifest-Version: 1.0
Built-By: baeldung
Created-By: 11.0.3 (AdoptOpenJDK)

3.3. Maven

Now, the contents of the default manifest file change depending on which tools we use.

For example, Maven adds some extra headers:

Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Created-By: Apache Maven 3.3.9
Built-By: baeldung
Build-Jdk: 11.0.3

We can actually customize these headers in our pom.

Say, for example, that we want to indicate who the JAR was created by and the package:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <archive>
            <manifest>
                <packageName>com.baeldung.java</packageName>
            </manifest>
            <manifestEntries>
                <Created-By>baeldung</Created-By>
            </manifestEntries>
        </archive>
    </configuration>
</plugin>

This produces a manifest file with a custom package and created-by headers:

Manifest-Version: 1.0
Build-Jdk-Spec: 11
Package: com.baeldung.java
Created-By: baeldung

Refer to the Maven JAR plugin documentation for a complete list of the options.

4. Headers

A header must follow a certain format and be separated by a new line:

key1: value1
Key2: value2

A valid header must have a space between the colon and the value. Another important point is there must be a new line at the end of the file. Otherwise, the last header is ignored.

Let's look at some of the standard headers from the specification and some common custom headers.

4.1. Main Headers

Main headers typically provide general information:

  • Manifest-Version: the version of the specification
  • Created-By: the tool version and vendor that created the manifest file
  • Multi-Release: if true, then this is a Multi-Release Jar
  • Built-By: this custom header gives the name of the user that created the manifest file

4.2. Entry Point and Classpath

If our JAR contains a runnable application then we can specify the entry point. Similarly, we can provide the classpath. By doing so, we avoid having to specify it when we want to run it.

  • Main-Class: the package and name of the class with a main method (no .class extension)
  • Class-Path: a space separated list of relative paths to libraries or resources

For example, if our application entry point is in Application.class and it uses libraries and resources then we can add the needed headers:

Main-Class: com.baeldung.Application
Class-Path: core.jar lib/ properties/

The classpath includes core.jar and all the files in the lib and properties directories. These assets are loaded relative to where the JAR is executed and not from within the JAR itself. In other words, they must exist outside the JAR.

4.3. Package Version and Sealing

These standard headers describe the packages within the JAR.

  • Name: the package
  • Implementation-Build-Date: the build date for the implementation
  • Implementation-Title: the title of the implementation
  • Implementation-Vendor: the vendor for the implementation
  • Implementation-Version: the implementation version
  • Specification-Title: the title for the specification
  • Specification-Vendor: the vendor for the specification
  • Specification-Version: the specification version
  • Sealed: if true then all the classes for the package come from the same JAR (default is false)

For example, we find these manifest headers in the MySQL driver Connector/J JAR. They describe the version of the JDBC specification the JAR meets, as well as the version of the driver itself:

Specification-Title: JDBC
Specification-Version: 4.2
Specification-Vendor: Oracle Corporation
Implementation-Title: MySQL Connector/J
Implementation-Version: 8.0.16
Implementation-Vendor: Oracle

4.4. Signed Jar

We can digitally sign our JAR to add extra security and verification. While this process is outside the scope of this article, doing so adds standard headers showing each signed class and its encoded signature to the manifest file. Please see the JAR signing documentation for more details.

4.5. OSGI

It's common to also see the custom headers for OSGI bundles:

  • Bundle-Name: title
  • Bundle-SymbolicName: a unique identifier
  • Bundle-Version: version
  • Import-Package: packages and versions the bundle depends on
  • Export-Package: bundle packages and versions available for use

See our Introduction to OSGI article to learn more about OSGI bundles.

5. Sections

There are two types of sections in a manifest file, main and per-entry. Headers that appear in the main section apply to everything in the JAR.  Whereas headers that appear in the per-entry sections only apply to the named package or class.

In addition, a header appearing in a per-entry section overrides the same header in the main section. It is common for per-entry sections to contain information on package versions and sealing plus digital signing.

Let's look at a simple example of a per-entry section:

Implementation-Title: baeldung-examples 
Implementation-Version: 1.0.1
Implementation-Vendor: Baeldung
Sealed: true

Name: com/baeldung/utils/
Sealed: false

The main section at the top has sealed all packages within our JAR. However, the package com.baeldung.utils is unsealed by the per-entry section.

6. Conclusion

This article provides an overview of how to add a manifest file to a JAR, how to use sections and some common headers. The structure of the manifest file allows us to provide standard information, such as version information.

However, its flexibility allows us to define whatever information we find relevant to describe the content of our JARs.

Java bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE
Comments are closed on this article!