The "forward compatibility" problem

The problem this JEP is trying to solve is to make it possible to use new JDK features even though the codebase must stay compatible with earlier versions.

Let's try to make this concrete with a real world example: In Java 7 java.nio was added, which was much better in File handling. In those days Maven still required Java 6 to run, however they wanted to make use of these new features when Maven was running on Java 7 or beyond.

Up until Java 8 there were 2 solutions:

• Compile with the targeted JDK (i.e. Java 6) and use reflection. You can ensure that the code is Java 6 compatible, but the reflection-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 
      ...
    }

• Compile with the required JDK (i.e. Java 7), but use source/target of the lowest version (i.e. 1.6). The danger here is that you cannot ensure that all code is Java 6 compatible. Depending on the code structure Animal Sniffer might help.

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

The "forward compatibility" solution

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 flag in the MANIFEST file, the Java runtime will also look inside META-INF/versions for version specific classes, otherwise only the base classes are used.

Challenges

The theory behind multi release jars is quite simple, but in practice it can become quite complex. You must ensure that all classes stay in sync; if you add a method to one class, don't forget to add it to the other classes as well. There are some options which should reduces problems at this level: Let all multirelease classes implement an interface and in the basecode instantiate the class but only call the interface methods. The best is to test the *jar* with all targeted Java versions. You should think twice before turning your jar into a multi release jar, because such jars can be hard to read, maintain and test. In general applications don't need this, unless it is a widely distributed application and you don't control the targeted Java runtime. Libraries should make a decision based on: do I need this new Java feature? Can I make this Java version the new requirement? Would it be acceptable to solve this with an else/if-statement as mentioned in the first paragraph?

There are a couple of important facts one should know when creating Multi Release jars.

• The Java compiler must be called for every different version. The solutions solve this either by having multiple Maven Projects/Modules or by adding extra execution-blocks to the pom.
• The Multi-Release: true attribute is only recognized when the classes are in a jar. In other words, you cannot test the classes put in target/classes/META-INF/versions/${release}/.
• Up until the moment of writing all IDEs can only have one JDK per Maven Project, whereas with multi release you want to specify it per source folder.

Single Project

In this case everything stays inside one Maven project. Every specific Java version get its own source folder and output folder, and just before packaging they are combined. What's not covered is how to test every class.

Multi-Release Parent

This approach replaces the maven-ant-plugin with extra exucution blocks in the maven-compiler-plugin. It has been setup as a parent, so other projects can use it. It uses toolchains to be able to build all classes with their matching Java version, so you always get the multi release jar. Because of the huge configuration and since Maven doesn't support mixins yet, it makes sense to put it all in a parent. However, at the same time surefire is only called once.

CI-server

This approach reduces the previous solution by only specifying execution blocks for sources for a specific Java version. It doesn't use toolchains, but the JDK used to run Maven. This means that only the sources up to the specific Java version are compiled and tested. This solution relies heavily on a CI-server where every targeted Java version is available. If the CI-server succeeds, then all classes are tested with their matching Java version.