.JAR File Format – META-INF and layout

The META-INF folder

Signature file extensions are 1 to 3 letters or digits, and unrecognised ones are ignored. Resources under META-INF/ cannot be versioned, service configuration included.

Service provider files

A JAR that provides an implementation of a service (an interface or abstract class found with java.util.ServiceLoader) on the class path, or as an automatic module, lists it in META-INF/services/service, where the file name is the service type’s fully qualified binary name.

• UTF-8 text, one fully qualified provider class name per line, no duplicates.
• Spaces, tabs and blank lines are ignored; # starts a comment to the end of the line.
• Each provider class must have a constructor taking no arguments, so it can be created when it is looked up.

# META-INF/services/java.io.spi.CharCodec
sun.io.StandardCodec    # Standard codecs for the platform

Multi-release JARs

With Multi-Release: true in the manifest’s main section, a JAR can hold different versions of classes for different Java releases (Java 9 and later).

• Versioned files go in META-INF/versions/N/, where N matches {1-9}{0-9}*; folders with N below 9 or not of that form are ignored.
• On Java N, a class loader looks in versions/N/, then each lower version folder down to 9, then the root.
• A class under version N must have a class file version no newer than Java N’s. A public or protected class there must replace a class of the same name and access in the root or a lower version; the public API must be exactly the same in every version.
• The boot class loader does not support them (with -Xbootclasspath/a they act as ordinary JARs). They can be signed.
• A modular multi-release JAR may have module-info.class at the root or directly in a version folder (even only there). A newer descriptor must equal the older one, except that non-transitive requires of java.* and jdk.* modules, and uses clauses, may differ. Public classes in non-exported packages need not replace a root class.

META-INF/MANIFEST.MF          (Multi-Release: true)
com/example/Util.class        Java 8 version
META-INF/versions/11/com/example/Util.class
META-INF/versions/17/com/example/Util.class

Modular and automatic modules

A JAR with module-info.class at its root is a modular JAR: an explicit module on the module path, an ordinary JAR on the class path. A JAR without one on the module path is an automatic module, named by the manifest’s Automatic-Module-Name or else from the file name by the rules of ModuleFinder.of.

JAR index (INDEX.LIST)

Added in Java 1.3 so that applets and network applications could find which JAR holds a class without downloading every JAR. jar -i wrote META-INF/INDEX.LIST in the first JAR of the class path. The current specification no longer describes it.

index file :   version-info blankline section*
version-info : JarIndex-Version: version-number
version-number : digit+{.digit+}*
section :      body blankline
body :         header name*
header :       char+ .jar newline
name :         char+ newline
char :         any valid Unicode character except NUL, CR and LF
blankline :    newline newline
newline :      CR LF | LF | CR (not followed by LF)

Each section starts with a JAR’s path (relative to the root JAR) and lists, one per line, the packages (as folder paths), resource folders and, for the unnamed package and root folder only, single files that it holds. A package split over several JARs appears in each. The loader trusted the index completely: a class missing from the JAR the index named raised InvalidJarIndexException.

JarIndex-Version: 1.0

app.jar
com/example
com/example/ui

lib/library.jar
org/library

Sources

JAR File Specification, Java SE 21 (“Modular JAR files”, “The META-INF directory”, “Multi-release JAR files”) and Java SE 8 (“JAR Index”, “Service Provider”). Not covered: ZIP-level details written by the jar tool, which the specification does not define.