Multi-Release Jar Files

1. Overview

Java is constantly evolving and adding new features to the JDK. And, if we want to use those features in our APIs, then that can obligate downstream dependencies to upgrade their JDK version.

Sometimes, we are forced to wait on using new language features in order to remain compatible.

In this tutorial, though, we’ll learn about Multi-Release JARs (MRJAR) and how they can simultaneously contain implementations compatible with disparate JDK versions.

2. Simple Example

Let’s take a look at a utility class called DateHelper that has a method to check for leap years. Let’s assume that it was written using JDK 7 and built to run on JRE 7+:

public class DateHelper {
    public static boolean checkIfLeapYear(String dateStr) throws Exception {
        logger.info("Checking for leap year using Java 1 calendar API ");

        Calendar cal = Calendar.getInstance();
        cal.setTime(new SimpleDateFormat("yyyy-MM-dd").parse(dateStr));
        int year = cal.get(Calendar.YEAR);

        return (new GregorianCalendar()).isLeapYear(year);
    }
}

The checkIfLeapYear method would be invoked from the main method of our test app:

public class App {
    public static void main(String[] args) throws Exception {
        String dateToCheck = args[0];
        boolean isLeapYear = DateHelper.checkIfLeapYear(dateToCheck);
        logger.info("Date given " + dateToCheck + " is leap year: " + isLeapYear);
    }
}

Let’s fast forward to today.

We know that Java 8 has a more concise way to parse the date. So, we’d like to take advantage of this and rewrite our logic. For this, we need to switch to JDK 8+. However, that would mean our module would stop working on JRE 7 for which it was originally written.

And we don’t want that to happen unless absolutely required.

3. Multi-Release Jar Files

The solution in Java 9 is to leave the original class untouched and instead create a new version using the new JDK and package them together. At runtime, the JVM (version 9 or above) will call any one of these two versions giving more preference to the highest version that the JVM supports.

For example, if an MRJAR contains Java version 7 (default), 9 and 10 of the same class, then JVM 10+ would execute version 10, and JVM 9 would execute version 9. In both cases, the default version is not executed as a more appropriate version exists for that JVM.

Note that the public definitions of the new version of the class should exactly match the original version. In other words, we’re not allowed to add any new public APIs exclusive to a new version.

4. Folder Structure

As classes in Java map directly to files by their names, creating a new version of DateHelper in the same location is not possible. Hence, we need to create them in a separate folder.

Let us start by creating a folder java9 at the same level as java. After that, let’s clone the DateHelper.java file retaining its package folder structure and place it in java9:

src/
    main/
        java/
            com/
                baeldung/
                    multireleaseapp/
                        App.java
                        DateHelper.java
        java9/
            com/
                baeldung/
                    multireleaseapp/
                        DateHelper.java

Some IDEs that don’t yet support MRJARs may throw errors for duplicate DateHelper.java classes.

We’ll take up how to integrate this with build tools like Maven in another tutorial. For now, let’s just focus on the fundamentals.

5. Code Changes

Let’s rewrite the logic of the java9 cloned class:

public class DateHelper {
    public static boolean checkIfLeapYear(String dateStr) throws Exception {
        logger.info("Checking for leap year using Java 9 Date Api");
        return LocalDate.parse(dateStr).isLeapYear();
    }
}

Note here that we’re not making any changes to the public method signatures of the cloned class but only changing the inner logic. At the same time, we’re not adding any new public methods.

This is very important because the jar creation will fail if these two rules are not followed.

6. Cross-Compilation in Java

Cross-compilation is the feature in Java that can compile files for running on earlier versions. This means there is no need for us to install separate JDK versions.

Let’s compile our classes using JDK 9 or above.

Firstly, compile the old code for the Java 7 platform:

javac --release 7 -d classes src\main\java\com\baeldung\multireleaseapp\*.java

Secondly, compile the new code for the Java 9 platform:

javac --release 9 -d classes-9 src\main\java9\com\baeldung\multireleaseapp\*.java

The release option is used to indicate the version of Java compiler and target JRE.

7. Creating the MRJAR

Finally, create the MRJAR file using version 9+:

jar --create --file target/mrjar.jar --main-class com.baeldung.multireleaseapp.App
  -C classes . --release 9 -C classes-9 .

The release option followed by a folder name makes the contents of that folder to be packaged inside the jar file under the version number value:

com/
    baeldung/
        multireleaseapp/
            App.class
            DateHelper.class
META-INF/
    versions/
        9/
            com/
                baeldung/
                    multireleaseapp/
                        DateHelper.class
    MANIFEST.MF

The MANIFEST.MF file has the property set to let the JVM know that this is an MRJAR file:

Multi-Release: true

Consequently, the JVM loads the appropriate class at runtime.

Older JVMs ignore the new property that indicates this is an MRJAR file and treat it as a normal JAR file.

8. Testing

Finally, let’s test our jar against Java 7 or 8:

> java -jar target/mrjar.jar "2012-09-22"
Checking for leap year using Java 1 calendar API 
Date given 2012-09-22 is leap year: true

And then, let’s test the jar again against Java 9 or later:

> java -jar target/mrjar.jar "2012-09-22"
Checking for leap year using Java 9 Date Api
Date given 2012-09-22 is leap year: true

9. Conclusion

In this article, we’ve seen how to create a multi-release jar file using a simple example.