Migrate to later Java versions. Automatically.

What is this?

This project implements a Rewrite module that performs common tasks when migrating to a new version of either Java and/or J2EE.

Browse a selection of recipes available through this module in the recipe catalog.

Java

In releases of Java prior to Java 11, it was not uncommon for there to be more than three years between major releases of the platform. This changed in June 2018 when a new, six-month release cadence was adopted by the OpenJDK community. The new model allows features to be released within any six-month window allowing features to be incrementally introduced when they are ready. Additionally, there are Java LTS (Long term support) releases on which there exists enterprise support offered through several vendors that provide builds of the JVM, compiler, and standard libraries. The current LTS versions of the Java platform (Java 8, 11, 17, and 21) are the most common versions in use within the Java ecosystem.

Java EE/Jakarta EE

The Java Platform, Enterprise Edition (Java EE) consists of a set of specifications that extend Java Standard Edition to enable the development of distributed applications and web services. Examples of the most commonly used parts of Java EE include JAXB, JAX-WS, and the activation framework. These APIs and their associated reference implementations were bundled with the Java standard library in JDK 6 through JDK 8 and deprecated in JDK 9. Starting with JDK 11, the libraries were removed from the standard library to reduce the footprint of the Java standard library (See JEP 320 for details).

Any projects that continue to use the JAXB framework (on JDK 11+) must now explicitly add the JAXB API and a runtime implementation to their builds.

To muddy the waters further, the governance of the Java Platform, Enterprise Edition, was transferred to the Eclipse Foundation and was renamed to Jakarta EE. The Jakarta EE 8 release (the first under the Jakarta name) maintains the javax.xml.bind package namespace, whereas Jakarta EE 9 is the first release where the package namespace was changed to jakarta.xml.bind:

Java Architecture for XML Binding (JAXB)

Java Architecture for XML Binding (JAXB) provides a framework for mapping XML documents to/from a Java representation of those documents. The specification/implementation of this library that is bundled with older versions of the JDK was part of the Java EE specification before it was moved to the Jakarta project. It can be confusing because Java EE 8 and Jakarta EE 8 provides exactly the same specification (they use the same javax.xml.bind namespace), and there are two different reference implementations for the specification.

Java API for XML Web Services (JAX-WS)

Java API for XML Web Services (JAX-WS) provides a framework for building SOAP-based XML web services in Java. This framework was originally part of the Java Platform, Enterprise Edition (J2EE), and both the API and the reference implementation was governed as part of the J2EE specification.

Java Migration Recipes

OpenRewrite provides a set of recipes that will help developers migrate to either Java 11, Java 17, or Java 21. These LTS releases are the most common targets for organizations that are looking to modernize their applications.

Java 11 Migrations

OpenRewrite provides a set of recipes that will help developers migrate to Java 11 when their existing application workloads are on Java 8 through 10. The biggest obstacles for the move to Java 11 are the introduction of the module system (in Java 9) and the removal of J2EE libraries that were previously packaged with the core JDK.

The composite recipe for migrating to Java 11 org.openrewrite.java.migrate.Java8toJava11 will allow developers to migrate applications that were previously running on Java 8 through 10. This recipe covers the following themes:

• Applications that use any of the Java EE specifications will have those dependencies migrated to Jakarta EE 8. Additionally, the migration to Jakarta EE 8 will also add explicit runtime dependencies on those projects that have transitive dependencies on the Jakarta EE APIs. Currently, only Maven-based build files are supported.
• Applications that use maven plugins for generating source code from XSDs and WSDLs will have their plugins updated to use a version of the plugin that is compatible with Java 11.
• Any deprecated APIs in the earlier versions of Java that have a well-defined migration path will be automatically applied to an application's sources. The remediations included with this recipe were originally identified using a build plugin called Jdeprscan.
• Illegal Reflective Access warnings will be logged when an application attempts to use an API that has not been publicly exported via the module system. This recipe will upgrade well-known, third-party libraries if they provide a version that is compliant with the Java module system. See Illegal Reflective Access for more information.

Java 17 Migrations

OpenRewrite provides a set of recipes that will help developers migrate to Java 17 when their existing application workloads are on Java 11 through 16. The composite recipe org.openrewrite.java.migrate.UpgradeToJava17 will cover the following themes:

• Any deprecated APIs in the earlier versions of Java that have a well-defined migration path will be automatically applied to an application's sources. The remediations included with this recipe were originally identified using a build plugin called Jdeprscan.
• Illegal Reflective Access errors are fatal in Java 17 and will result in the application terminating when an application or a third-party library attempts to access an API that has not been publicly exported via the module system. This recipe will upgrade well-known, third-party libraries if they provide a version that is compliant with the Java module system.

Java 21 Migrations

OpenRewrite provides a set of recipes that will help developers migrate to Java 21 when their existing application workloads are on Java 11 through 20. The composite recipe org.openrewrite.java.migrate.UpgradeToJava21 will cover the following themes:

• everything covered by the Java 17 Migration
• initial support for the migration to Sequenced collections

Illegal Reflective Access

The Java module system was introduced in Java 9 and provides a higher-level abstraction for grouping a set of Java packages and resources along with additional metadata. The metadata is used to identify what services the module offers, what dependencies the module requires, and provides a mechanism for explicitly defining which module classes are “visible” to Java classes that are external to the module.

The module system provides strong encapsulation and the core Java libraries, starting with Java 9, have been designed to use the module specification. The rules of the module system, if strictly enforced, introduce breaking changes to downstream projects that have not yet adopted the module system. In fact, it is very common for a typical Java application to have a mix of module-compliant code along with code that is not aware of modules.

Even as Java has reached Java 15, there are a large number of applications and libraries that are not compliant with the rules defined by the Java module system. Rather than breaking those libraries, the Java runtime has been configured to allow mixed-use applications. If an application makes an illegal, reflective call to a module’s unpublished resource, a warning will be logged.

The default behavior, starting with Java 11, is to log a warning the first time an illegal access call is made. All subsequent calls will not be logged, and the warning looks similar to the following:

WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by com.thoughtworks.xstream.core.util.Fields (file.....)
WARNING: Please consider reporting this to the maintainers of com.thoughtworks.xstream.core.util.Fields
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

This warning, while valid, produces noise in an organization's logging infrastructure. In Java 17, these types of issues are now fatal and the application will terminate if such illegal access occurs.

Suppressing Illegal Reflective Access Exceptions.

In situations where a third-party library does not provide a version that is compliant with the Java module system, it is possible to suppress these warnings/errors. An application may add Add-Opens declarations to its top-level JAR's manifest:

<Add-Opens>
    java.base/java.lang java.base/java.util java.base/java.lang.reflect java.base/java.text java.desktop/java.awt.font
</Add-Opens>

This solution will suppress the warnings and errors in the deployed artifacts while still surfacing the warning when developers run the application from their development environments.

NOTE: You cannot add these directives to a library that is transitively included by an application. The only place the Java runtime will enforce the suppressions when they are applied to the top-level, executable Jar.

There are currently no recipes that will automatically apply "" directives to Jar manifests.

Helpful tools

• http://ibm.biz/WAMT4AppBinaries

Contributing

We appreciate all types of contributions. See the contributing guide for detailed instructions on how to get started.