skip to content

What is a Java multi-release JAR, how do META-INF/versions and the Multi-Release attribute select classes, and when is it worth using over separate artifacts?

level: seniorimportance: nice to knowfreq 24%

answer

  1. one archive, several releases
  2. attribute switches it on
  3. highest directory not above the running release
  4. same public API in every version
  5. plain JarFile sees root entries

basics

~20 s

A multi-release JAR, added in Java 9, carries Multi-Release: true and class overlays under META-INF/versions/N. The runtime loads the highest N not above its own release, else the root copy. Use it for small version-specific internals behind one API.

solid answer

~40 s

A multi-release JAR (JEP 238, Java 9) holds one library with several implementations behind the same public API: base classes at the root, compiled for the oldest supported release, and overrides under `META-INF/versions/N`. With `Multi-Release: true` in the manifest's main section, a class loader looks in the directory for the running release, then lower ones, then the root. Earlier libraries used a reflective check at class initialization, or shipped one artifact per platform. It suits a library that must keep an old baseline yet wants a newer API, such as `VarHandle`, in a few classes. Separate artifacts or a raised baseline are better when the API or dependencies differ, because one JAR is one release. Each branch also needs tests on its own JDK.

code

java · 16 lines
java
import java.io.File;
import java.util.jar.JarFile;
import java.util.zip.ZipFile;

public class WhichEntry {
    public static void main(String[] args) throws Exception {
        File file = new File(args[0]);
        String name = args[1];
        try (JarFile plain = new JarFile(file);
             JarFile runtime = new JarFile(file, true, ZipFile.OPEN_READ, JarFile.runtimeVersion())) {
            System.out.println("isMultiRelease: " + plain.isMultiRelease());
            System.out.println("plain:   " + plain.getJarEntry(name).getRealName());
            System.out.println("runtime: " + runtime.getJarEntry(name).getRealName());
        }
    }
}

go deeper

for a junior

Recall that one JAR can hold classes for several Java releases, that META-INF/versions/N holds the overrides, and that the Multi-Release: true attribute switches this on.

for a middle

Explain the search order: the running release's directory, then lower ones, then the root. Mention that a plain new JarFile(path) reads root entries unless it is built with a runtime version.

for a senior

Show the judgment: a small overlay behind one identical public API is worth it, while differing APIs, differing dependencies or large overlays are not. Mention that each branch needs its tests run on its own JDK.

for a principal

Treat it as a support-policy decision: how long the team pays for an old baseline. A multi-release JAR postpones that decision at the cost of extra builds and tests, so weigh it against raising the baseline outright.

## The problem it solves A library usually supports several Java releases, which makes newer APIs hard to use. Before Java 9 it had two routes, and JEP 238 lists the limits of the first: - **A reflective check.** Compile for the old release, test at class initialization whether a newer API exists, and select an implementation class. The checks need careful maintenance, newer language features stay out of reach, and code that depends on a removed API fails to compile. - **One artifact per platform.** Publish a separate build for each Java version and let users choose. A **multi-release JAR** (JEP 238, Java 9) packs the variants into one archive, and the running JVM selects among them. ## Layout and the attribute ```text lib.jar META-INF/MANIFEST.MF Multi-Release: true lib/Rt.class for the oldest supported release lib/Other.class META-INF/versions/11/lib/Rt.class META-INF/versions/21/lib/Rt.class ``` - **`Multi-Release: true`** belongs in the manifest's main section. Without it, `META-INF/versions` is ignored and the root classes load. - The value is case-insensitive, but a trailing space, or two spaces after the colon, switches the feature off silently. `java.util.jar.JarFile`'s private `checkForSpecialAttributes` first searches the manifest bytes for that text, ignoring case, and only then parses the value with `Boolean.parseBoolean`. The quick search keeps ordinary JARs fast. - **Directories are named by major release**, 9 or greater, under `META-INF/versions/`. - **Resources under `META-INF` cannot be versioned**, so the manifest and `META-INF/services` have one copy each. ## How selection works On release `R`, a class loader looks for an entry in this order: 1. `META-INF/versions/R/` 2. Lower version directories, highest first 3. The JAR root So the layout above gives: | Running Java | `lib/Rt` comes from | `lib/Other` comes from | |---|---|---| | 8 to 10 | root | root | | 11 to 20 | `versions/11` | root | | 21 and later | `versions/21` | root | A Java 8 JVM knows nothing of the format and sees only the root. Selection is opt-in for each `JarFile`: - The JDK's class loaders open JARs with a runtime version, `new JarFile(file, true, ZipFile.OPEN_READ, JarFile.runtimeVersion())`. - A plain `new JarFile(path)` uses the base version. `getEntry` returns the root copy and `getVersion()` reports 8, although `isMultiRelease()` still returns true. - `JarEntry.getName()` gives the base name and `getRealName()` the versioned path. A resource URL from a class loader points straight into `META-INF/versions/N`. - The boot class loader does not support the format, so classes from a JAR appended with `-Xbootclasspath/a` come from the root. - The system properties `jdk.util.jar.enableMultiRelease` and `jdk.util.jar.version` override the behaviour, as an implementation note on `JarFile` describes. ## What may differ between versions The JAR specification requires the public API to be **exactly the same** across versions, and a runtime is not required to verify that. The `jar` tool does check when you build with `--release`: ```text jar --create --file lib.jar -C base . --release 11 -C v11 . --release 21 -C v21 . ``` - It adds the `Multi-Release` attribute for you. - It rejects a public class whose API differs, a class file newer than the directory's release, and a new public class. In a modular JAR, a new public class in a package the module does not export draws only a warning, because the specification exempts such classes. - It accepts changed method bodies, an older class file, and non-public helper classes that exist only in a versioned directory. - A hand-assembled archive skips these checks, and the runtime loads it anyway. Compile each set with `javac --release N`. `javac` 27 still accepts `--release 8`, with a warning that the value is obsolete and will be removed in a future release. ## When it is worth it This is a judgment about cost, with no single right answer. | Option | Fits when | Main cost | |---|---|---| | Raise the baseline | Users are already on newer releases | Drops users on old releases | | Multi-release JAR | Same API, few classes differ, one release of the library | Several compile steps, and tests on each JDK | | Separate artifacts | The API or the dependencies differ | Users must choose, and releases multiply | A multi-release JAR earns its place in a library with a stubborn old baseline and a few classes that want a newer API, such as moving field access to `VarHandle` while still supporting Java 8. An application rarely needs one, because it chooses its own JDK. Three costs are easy to miss: - **Testing.** Running the tests on one JDK exercises one branch, so every overlay needs its tests run on a JDK that selects it. - **Readers.** JEP 238 notes that class loaders reading through `ZipFile` are not aware of the format, so custom loaders need checking. - **Repackaging.** Merging into a single archive, as a fat JAR build does, can lose the attribute or the directories, and the code then falls back to root classes with no error. A multi-release JAR is one unit of release with one version, so a difference that needs its own version or dependency list belongs in a separate artifact.

  • Why does `new JarFile(path).getEntry("lib/Rt.class")` return the root copy from a multi-release JAR?
    A plain `JarFile` is configured with the base version, so it reads like an ordinary JAR, although `isMultiRelease()` still returns true. Selection needs `new JarFile(file, true, ZipFile.OPEN_READ, JarFile.runtimeVersion())`, which is how the JDK's class loaders open JARs. `getRealName()` on the returned entry shows which path you got.
  • Can a class under `META-INF/versions/11` add a public method the root copy lacks?
    It must not: the JAR specification requires the public API to be exactly the same across versions. `jar --release 11` rejects it, but a runtime is not required to check, so a hand-built archive would still load, leaving callers of that method to fail on older releases. Non-public helper classes are allowed in a versioned directory.
  • Can a multi-release JAR carry a different `module-info.class` for each version?
    Only within limits. JEP 238 requires a versioned descriptor to match the root one, except for non-transitive `requires` of `java.*` and `jdk.*` modules and for `uses` clauses, which it treats as implementation details. Changing what the module exports or its other dependencies calls for a new version of the module.

  • META-INF/versions directories take effect even without the Multi-Release attribute.
  • The JVM loads the highest versioned directory in the JAR, whatever release it runs.
  • If no directory matches the running release exactly, the JVM reports an error.
  • Each versioned directory can expose its own public API, since only one is loaded.
  • The class loader verifies at run time that overlays keep the same public API.
  • A plain new JarFile(path) returns the entry for the running release.

Multi-release JAR files
Java 9

Assumes Java 27; the format dates from Java 9, and selection follows the running JVM's major release.

context