The Problem

A library must stay compatible with earlier Java versions but would like to use new JDK features when it runs on a newer one. For example, java.nio.file was added in Java 7 and handles files much better, while Maven itself still required Java 6 at the time.

Without multi-release JARs there are two solutions:

1. Compile with the targeted JDK (Java 6) and use reflection. The code is guaranteed to be Java 6 compatible, but the reflective part is hard to verify.

   if (isAtLeastJava7()) {
       Method toPathMethod = f.getClass().getMethod("toPath");
       Object toPathInstance = toPathMethod.invoke(f);
       Method isSymbolicLink = Class.forName("java.nio.file.Files").getMethod("isSymbolicLink");
       ...
   } else {
       // compare absoluteFile with canonicalFile
       ...
   }
   

2. Compile with the required JDK (Java 7), but with source and target set to the lowest version (1.6). The danger is that you cannot ensure that all code is Java 6 compatible. Depending on the code structure, Animal Sniffer can help.

   if (isAtLeastJava7()) {
       return Files.isSymbolicLink(f.toPath());
   } else {
       // compare absoluteFile with canonicalFile
       ...
   }
   

The Solution

A multi-release JAR keeps the base classes at the root and the version-specific ones under META-INF/versions:

A.class
B.class
C.class
D.class
META-INF/MANIFEST.MF { Multi-Release: true }
         versions/9/A.class
                    B.class
                  10/A.class
                     C.class

With the Multi-Release: true attribute in the manifest, the Java runtime also looks inside META-INF/versions for version-specific classes. Without it, only the base classes are used. The maven-jar-plugin adds the attribute by itself when the JAR contains a META-INF/versions directory (detectMultiReleaseJar, enabled by default). To set it explicitly, add it with the archive configuration, see Working with Manifests:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <version>3.5.1</version>
  <configuration>
    <archive>
      <manifestEntries>
        <Multi-Release>true</Multi-Release>
      </manifestEntries>
    </archive>
  </configuration>
</plugin>

The Compiler Plugin can place the output of an execution in META-INF/versions/${release} for you: set release together with multiReleaseOutput to true in an additional execution.

Challenges

The theory is simple, but in practice multi-release JARs get complex. Think twice before turning a JAR into one, because such JARs are hard to read, maintain and test. Applications rarely need this, unless the application is widely distributed and you do not control the targeted Java runtime. Libraries should ask: do I need this new Java feature? Can I make this Java version the new requirement? Would an if/else as in the first solution above be acceptable?

Keep these facts in mind:

• All classes must stay in sync. If you add a method to one class, add it to the other versions as well. Letting all multi-release classes implement an interface, and only calling the interface methods from the base code, reduces the risk. The best protection is to test the JAR with all targeted Java versions.
• The Java compiler must be called once per Java version, either with multiple Maven projects or modules, or with extra compiler executions in the POM (as older projects with a module-info do, see the Compiler Plugin's module-info example).
• The Multi-Release: true attribute is only recognized when the classes are in a JAR, so you cannot test the classes in target/classes/META-INF/versions/${release}/.
• IDEs support one JDK per Maven project, whereas with multi-release JARs you want to choose it per source folder.

Patterns

There are several patterns to build a multi-release JAR with Maven. Integration tests for each pattern, built from the same sources, are in the Compiler Plugin's multirelease-patterns directory.