This proposal has been approved and the Eclipse Migration Toolkit for Java project has been created.
Visit the project page for the latest information and development.

Eclipse Migration Toolkit for Java

Wednesday, March 23, 2022 - 23:49 by Denghui Dong
This proposal is in the Project Proposal Phase (as defined in the Eclipse Development Process) and is written to declare its intent and scope. We solicit additional participation and input from the community. Please login and add your feedback in the comments section.
Parent Project
Proposal State

With the gradual popularity of Java 11 and the official release of Java 17, many applications that are still using Java 8 have begun to migrate to higher versions. During the migration process, developers will encounter many problems, hindering their progress.

The project goal is to simplify the migration of Java applications from previous versions of OpenJDK, especially those deemed as Long Term Service (LTS) release versions. That is:

  • from 8 to 11
  • from 8 to 17
  • from 11 to 17

The proposed migration toolkit supports examining application artifacts statically, including project source directories and applications archives, or running as a dynamic agent for runtime detection. The toolkit can produce the analysis results in different formats, including a raw TEXT file, JSON file, or HTML report highlighting areas that need changes for migration.


Eclipse Migration Toolkit for Java offers a toolkit that simplifies the migration of Java applications from previous versions of OpenJDK, especially those deemed as Long Term Service (LTS) release versions.

The toolkit contains core rule-based services available through different user interfaces, including a command-line interface (CLI), build automation tool plugins, a Java agent, and some other popular DevOps tooling as the project sees fit. Finally, it will produce various report formats (TEXT, JSON, HTML) to help developers migrate to the Java version. 

Participants in the project are responsible for developing, managing, and supporting technologies that:

  • Develop the rule-based services for the Java version migration. LTS versions are the primary focus.
    • Define the rule set for the best coverage in Incompatible/Internal/Deprecated/Removed JDK API usage, closely collaborate with the OpenJDK community, and maintain/enrich them along with the new OpenJDK release.
  • Develop the rule-based service for Java options migration across different OpenJDK versions
    • Define the ruleset to identify the Removed/Deprecated/Replaced/Recommended options while upgrading to the new JDK version.
  • Define the dependency checking rules for popular third-party libraries and engage third-party communities to maintain the validating relationship between the version of the third-party library and their supported Java release.
  • Implement the mechanism to analyze and detect the dependencies on the internal structure layout of JDK classes via Reflection API and the incompatibility issues introduced by Java modularity.
  • Support the integration with the automation build tools, such as Maven, Gradle, etc., via plugins.
  • Develop various friendly user interfaces, which rely on core rule-based services to assist the users for easy migration, including CLI, Web UI, and Agent.
  • Provide the results in different formats highlighting areas that need changes for the migration.
  • Provide documentation assistance for different version migrations.
  • Integrate with JDK built-in tools: jdeps and jdeprscan.

The Eclipse Migration Toolkit for Java is a tooling project for assisting the Java version migration. The project provides static/dynamic tools and documents that support the migration of Java applications from previous versions of OpenJDK. The needed changes are highlighted in the final analysis reports.

To better illustrate what the tool can provide, consider the user story like this:

1. Tom is a Java developer who is migrating his application from Java 8 to Java 11.

2. His application consists of 1000~ jars, written in 100,000~ lines of code. Tom reads related migration guides on the internet and finally finds it is tough to check/make all required changes in such a large codebase suggested by these migration docs.

3. Tom decides to use this toolset for his migration.

4. Tom attaches the Java agent in the toolset to his application when the application is started with Java 8. He runs all test cases of this application in the test environment. After completion, a compatibility report is generated for him.

5. Tom makes the required changes according to the capability report. He also uses the command-line tool to scan all jars of this application, ensuring all potential problems are fixed. 

6. After completing all changes suggested by the toolset, his application runs with Java 11 successfully.

Why Here?

The Eclipse Foundation has always been the home for vendor-neutral developer tools developed under open-source governance. We think the Eclipse community will help make it a diverse and successful open-source project. Software organizations have to tackle the challenges incurred by version migration when they best keep their projects valuable over a long time. We hope this project can help their projects succeed in the long term. Moreover, hosting this project at Eclipse will help more synergies with Adoptium and other Eclipse Java projects.

Future Work

After the initial contribution, we are planning to engage more parties to participate in and co-work with communities to:

  • Improve the static analysis tool, and reduce the false positive rate
  • Enhance the migration rule set, and the Java 17 migration support
  • Support the toolset integration with other EF Java projects
  • Explore the methods to automatically generate checking rules based on CSR (compatibility and specification review)
Source Repository Type

of an incompatibility that I might run into when trying to run/compile my Java 11 based application with a Java 17 JDK?

In reply to by Kai Hudalla

Thanks for the comment.

An example we encountered in practice is that some middleware will rely on the reflection API to obtain fields or methods of ClassLoader. JDK-8210496 restricts the reflection access of ClassLoader and some other special classes.

This kind of access works fine on 11 but runs into problems on 17, and the migration tool can help developers find code locations where this problem may occur.