Introduction

Do you have an application running on Java 8 (or even Java 7) and are wondering how much work it will take to get the application working on Java 11? The Migration Toolkit for Application Binaries is here to help! The tool can scan your applications for any potential issues you might run into when you move to Java 11.

About the Migration Toolkit for Application Binaries

The Migration Toolkit for Application Binaries has been around for years to help developers migrate from various Java SE and application server environments, both on-premises and in the cloud. One scenario that we’ve added support for over the years is helping developers upgrade to newer Java SE levels. We previously added migration rules that flag issues when migrating from Java 6 to Java 7 and Java 7 to Java 8. Now, we have support for migrating from Java 8 to Java 11. You may be asking, “What happened to Java 9 and 10?” Well, with Java 9 and 10, Oracle had announced that those versions only have short-term support (six months), and we figured that most developers would go through the big migration effort with a long-term supported release, which is Java 11. This tutorial highlights the tool features that are interesting from a Java 11 perspective; but if you want more information about the other scenarios, there are lots of resources available on the tool’s download page.

Resolve issues when migrating to Java 11

One of the biggest obstacles application developers will run into when migrating to Java 11 is the removal of the Java EE modules from the JDK. This means that if your application is using any classes that were in any of those modules (classes in javax.jws., javax.xml.ws., etc), those applications won’t run on Java 11 because they can’t access those classes. That was the bad news. The good news is that the Liberty team did a lot of work to make the removed Java EE modules available when you migrate to Java 11 on the Liberty application server (Open Liberty and WebSphere Liberty). All you’ll need to do for the missing Java EE packages is add the right feature to your server.xml, and your app will work again.

So, how do you know if your application is using any of those removed packages? How do you know which Liberty features to enable? What about the other changes that Java 11 introduced? How do you deal with those? That’s where the tool can help. I recommend that you start with the Migration Toolkit for Application Binaries. This tool will scan your application binaries (your .ear or .war file) and produce a report highlighting any potential Java 11 issues it finds in your application. If you’re using Eclipse, there is also a source scanner version of the tool that will inspect your source code and flag the same issues that the binary scanner looks for. The source scanner tool is useful when you determine that you need to make source code changes in your application because it lets you navigate to the exact line of code that needs to be addressed. Here is a video on how to use the source scanner to migrate to Java 11. This tutorial focuses on the binary scanner since it’s the first step to preparing your applications for migration.

Run the binary scanner to find Java 11 issues

  1. Download the Migration Toolkit for Application Binaries.

  2. In a command prompt window, run the following command to install the tool:

    java -jar binaryAppScannerInstaller.jar
    
  3. Follow the prompts to read/accept the license, and specify a target directory for the product files (press Enter to install in the current directory).

  4. Change directory:

    cd <target directory>\wamt
    
  5. Now you’re ready to run the tool against your application. You need to specify some information about your scenario in order to flag the relevant migration rules:

    • The application you want to run against
    • What application server you’re migrating from and what application server you’re migrating to
    • What Java version you’re migrating from and what Java version you’re migrating to

    Here is the command I ran to tell the binary scanner that I’m migrating from Liberty to Liberty and from Java IBM 8 to OpenJDK 11 (this command works for both Open Liberty and WebSphere Liberty):

    java -jar binaryAppScanner.jar C:\demo\Apps\MyApplication.war --sourceAppServer=liberty --targetAppServer=liberty --sourceJava=ibm8 --targetJava=openjdk11
    
  6. The report will take a few seconds/minutes to run, depending on the size of your application. When it’s done, it will produce an HTML report. The top of your generated HTML report shows you how many issues were flagged by the tool, if any. The HTML report includes four sections:

    • Application evaluation report
    • Application inventory report
    • Detailed migration analysis report
    • Liberty feature list configuration

    Feel free to read through the whole report, but what I’m really interested in here is the detailed migration analysis report. In my case, I ran the report against an application that uses some javax.xml.ws classes. So, I am getting this report that tells me that I have a warning rule flagged:

    alt

  7. To understand more about the issue that was flagged, so go to the “Detailed Migration Analysis section,” and click the Show details button:

    alt

  8. You now see the list of all the rules that were flagged. The title of the rule indicates that my problem is related to the java.xml.ws module being removed in JDK 11. To figure out how to resolve this issue, click the Show rule help button to get more information. If you’re curious about what class is using these packages, click Show results.

    alt

  9. After reading the rule help, I understand how to fix the issue. In my case, I see that if I want to regain access to the removed java.xml.ws module package, the solution is to add the jaxws-2.2 feature to my Liberty server.xml file. I go add it to my Liberty server.xml file (if it wasn’t already there), and now my app starts working again! (If you have a Liberty server running with Java 11, check out Andy Guibert’s blog on running Liberty with Java 11. Even if you don’t, check it out anyways — it’s a great blog post!)

    alt

There are dozens of migration rules that the tool is scanning for. For each rule, we have included migration advice and links to help you resolve these issues. You will want to go through each rule and read the help to determine what is the right course of action for your application. To get more information on the available binary scanner parameters run:

java -jar binaryAppScanner.jar --help --all

Notes

  • The migration tools help developers migrate from various Java environments, including moving from other application servers to Liberty or WebSphere traditional, WebSphere traditional to Liberty, on-premises to cloud, and other scenarios where developers may need help moving their apps.

  • The tools work the same for both Open Liberty and WebSphere Liberty.

  • When the migration rules were added to the application migration tools, we tried to include as much detection as possible into the tools. However, some of the Java 11 changes are outside the scope of the tools and could not be detected, such as certificate changes and other JVM options that were removed. The tool attempts to address application-related issues only, but if you’re curious about all the changes that went into Java 11, take a look at Oracle’s JDK 11 Migration Guide.