So you want to migrate to Java 11 but your Maven project is still sitting on Java 8? You don't care much about the new module system (Jigsaw) introduced in Java 9, you just want your application to run on the latest JDK version? Then this guide is for you. It includes everything I've learned while migrating our product to Java 11.
As of 2019 Oracle Java 8 will no longer receive free security updates. So now is the time to migrate to JDK 11.
Clean up your
The first thing you should do before even thinking about upgrading the Java version is to clean up your
pom.xml files. If your project is a multi-module Maven project then it helps to establish a parent POM and maintain
pluginManagement in this file. That way all your plugins and dependencies are defined in a single file and are not spread across multiple POM files what makes managing versions easier.
In order to migrate your project to the latest Java version 11 it's highly recommended to update as much plugins and dependencies to the latest stable version as possible. Many plugins such as the compiler plugin, surefire or failsafe are not compatible with Java 9 if you use older versions. Also a lot of libraries are incompatible without migrating to the latest version.
Make sure you have the versions plugin configured in your master POM:
This plugin helps finding the latest plugin or dependency versions for your modules. Open up the terminal and execute this command to find the plugin versions you have to update:
You will see a list of plugins used in your project with newer versions available. Update all of those plugins to the lastest stable version. After you've updated your plugin versions make sure that your project still compiles and runs properly.
You can use
mvn -N ...from your projects root directory to just check your parent POM in case of multi-module projects.
Configure plugins for Java 11
The most important plugins for Java 11 are the compiler plugin, surefire (for unit-tests) and failsafe (for integration-tests).
In order to compile your project for Java 11 add the
release configuration to the compiler plugin, a new compiler parameter to replace the
target version parameters:
Also don't forget to set your IDEs project SDK to same JDK version. In Intellij IDEA go to Module Settings -> Project -> SDK.
For surefire and failsafe plugins we add an additional argument
--illegal-access=permit to allow all reflection access for third party libraries:
This is only needed if your dependencies make heavy use of reflection. If you're unsure whether you need this you can add the
argLine later if your tests run into trouble.
You'll see warnings like this when a library tries to illegally access classes via
Keep in mind that later you probably also have to pass the
--illegal-access=permitparameter when starting your application.
As mentioned before the best thing you can do is to migrate all your dependencies to the latest stable versions to make sure everything works fine with Java 11. While many older dependencies might work just fine there's a couple of dependencies where version updates are mandatory, e.g. all those various bytecode enhancement libaries such as
byte-buddy. Those libraries often come as transitive dependencies so make sure at least those libaries are up-to-date.
This command helps to find outdated dependency versions from your modules:
Update as much libaries as possible to the latest stable version. If there's some dependency that you can't update due to compatibility issues in your project than leave it as is. Chances are that it just runs fine with Java 11.
Now is a good time to compile your project with JDK 11 for the first time:
Hint: You can speed up multi-module Maven projects by using parallel builds, e.g.
mvn -T 4 compilecompiles all modules in parallel on 4 CPU cores.
You will eventually face different compiler errors such as
ClassNotFoundException. Every project is different so I cannot provide solutions for every problem you will face. The rest of this article describes solutions to various problems we had to solve in order to run our application with JDK 11.
Add missing modules
With the introduction of the Java module system (Jigsaw) in Java 9 the Java standard libary has been divided into separate modules. While most classes are still available without any changes, some are not. You have to explicitely define which additional modules your application needs access to or you can just add those modules from the Maven central repository.
java --list-moduleslists all available modules.
When migrating our web project to Java 11 we had to add
javax.annotations to prevent
ClassNotFoundException. We've added the following libaries as additional Maven dependencies to our POMs:
Instead of adding those libaries via Maven we could utilize the
–add-modulesJava parameter to add additional JDK modules to the project.
While some classes have been moved to additional Java modules other classes can no longer been used in user code, namely classes from
sun.* packages and also some classes from
com.sun.*. If you get compiler errors because your code links to classes from those packages you have to remove those imports from your code.
Here's a few things we had to fix in our project:
sun.misc.BASE64Encoder: This can simply be replaced by
java.util.Base64.getEncoder()which is available since Java 8.
sun.reflect.generics.reflectiveObjects.ParameterizedTypeImpl: This class has accidentally been used in our code base and can simply be replaced by the interface type
sun.reflect.annotation.AnnotationParser: We use this class to programmatically create annotation instances. The class is no longer accessible but can be replaced by
AnnotationFactoryfrom Hibernate Validator.
com.sun.org.apache.xml.internal.utils.DefaultErrorHandler: We've replaced this class with a custom implementation of the interface.
We've encountered a curious case with number formats for locales such as
Locale.GERMANY which let a bunch of our tests fail with a rather strange assertion error:
The underlying code uses
NumberFormat.getCurrencyInstance(Locale.GERMANY) to format numbers into the german currency format. So what the heck is happening here?
Javas number formats have been modified to use non-breaking spaces instead of normal spaces between the number and the currency symbol. This change makes perfectly sense because it prevents line-breaks between the number and the currency symbol in various presentation formats. Changing the strings in our tests to use non-breaking spaces (use OPTION SPACE on Mac OSX keyboards) fixed this issue.
When running web applications with Apache Tomcat you need at least Apache Tomcat 7.0.85 or later. Otherwise Tomcat will not start on Java 9 and above and you would see the following error:
Also don't forget to eventually add the additional startup parameter
--illegal-access=permit to your servlet container.
I hope these tips are somewhat useful to you and helps you migrating your application from Java 8 to 11. If you like this guide please consider sharing the link with your followers. Also let me know on Twitter if your migration was successful.