Eclipse Migration Toolkit for Java (EMT4J)

EMT4J is a project that aims to simplify the Java version migration. At the moment, this project focuses on three LTS (i.e. Long-Term-Support) versions: 8, 11, 17 and 21. Therefore, if you want to migrate your application running on JDK 8/11/17 to JDK 11/17/21, then this project is for you.

EMT4J supports statically checking application artifacts including the project's classes and dependencies. It also supports running as a Java agent to perform runtime checking. During the checking process, EMT4J collects compatibility problems and outputs a report finally. It currently supports HTML, TEXT, and JSON formats. Users transform the project according to the report and finally complete the migration of the Java version.

Support for Java 21 and Autofix are introduced by version 0.9 which has not been released yet. If you want to use these two features, you need to manually install EMT4J to your local Maven repository.

How to use

Maven Plugin

Find compatibility problems existing in a Maven project

Add the following configuration to pom.xml (root pom.xml if a multi-module project):

<build>
    <plugins>
        <plugin>
            <groupId>org.eclipse.emt4j</groupId>
            <artifactId>emt4j-maven-plugin</artifactId>
            <version>0.8.0</version>
            <executions>
                <execution>
                    <phase>process-test-classes</phase>
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <fromVersion>8</fromVersion>
                <toVersion>11</toVersion>
                <outputFile>report.html</outputFile>
            </configuration>
        </plugin>
    </plugins>
</build>

Then run the following command:

$ mvn process-test-classes

EMT4J's report will be generated in the project directory.

Users can also run the following command directly without modifying pom.xml:

# run with default configurations
$ mvn process-test-classes org.eclipse.emt4j:emt4j-maven-plugin:0.8.0:process

# specify outputFile and priority by -D
$ mvn process-test-classes org.eclipse.emt4j:emt4j-maven-plugin:0.8.0:process -DoutputFile=emt4j-report.html -Dpriority=p1

Autofix

EMT4J running in the way of Maven plugin has the capability of automatically fixing compatability problems we found.

Steps to use:

• Execute EMT4J with the autofix option

$ mvn process-test-classes org.eclipse.emt4j:emt4j-maven-plugin:0.9.0:process -DautofixFile=fixed.patch -Dautofix=true

• Apply the patch using the command

$ git apply fixed.patch

If the project files include multiple file encodings, the above git apply step might fail. In this case, consider not generating a patch and directly writing the autofix results into the files, which can be done using the following command

$ mvn process-test-classes org.eclipse.emt4j:emt4j-maven-plugin:0.9.0:process -DautofixGeneratePatch=false -Dautofix=true

All available options for the Maven plugin:

Configurations:

• fromVersion: the JDK version that the project currently uses. 8, 11 and 21 are supported, and 8 is as default.

• toVersion: the target JDK version. 11, 17 and 21 are supported, and 11 is as default.

• outputFile: the destination of EMT4J's report. The default is emt4j-report.html.

• priority: the minimum rule priority. p1, p2, p3 and p4 are supported. The default is not set.

• verbose: print more detailed messages if true.

• check: Whether to scan for compatibility issues (to improve execution speed). The default is true.

• skipDeps: Whether to skip scanning dependencies. The default is false.

• autofix: Whether to perform autofix. The default is false.

• autofixGeneratePatch: If true, the result of the autofix will be written as a git patch file; if false, the result of the autofix is written directly into the corresponding files. The default is true.

• autofixFile: the destination of the patch file generated by autofix, effective only when autofixGeneratePatch is true. The default is emt4j-autofix.patch.

• unfixedReportFileName: the destination of the HTML report file for issues that cannot be fixed. The default is emt4j-autofix-unfixed.html.

• fixedReportFileName: the destination of the HTML report file for issues that are already fixed. The default is emt4j-autofix-fixed.html.

As mentioned earlier, EMT4J supports running as a Java agent. To leverage it in the test process you need to add the following configuration:

<build>
    <plugins>
        <plugin>
            <groupId>org.eclipse.emt4j</groupId>
            <artifactId>emt4j-maven-plugin</artifactId>
            <version>0.8.0</version>
            <executions>
                <execution>
                    <phase>initialize</phase>
                    <goals>
                        <goal>inject-agent</goal>
                    </goals>
                </execution>
                <execution>
                    <id>check</id>
                    <phase>test</phase>
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <fromVersion>8</fromVersion>
                <toVersion>11</toVersion>
                <outputFile>report.html</outputFile>
            </configuration>
        </plugin>
    </plugins>
</build>

Then run the following command:

$ mvn test

Find compatibility problems existing in specified files (classes, JAR, or directory)

$ mvn org.eclipse.emt4j:emt4j-maven-plugin:0.8.0:check-files -Dfiles=...

Java agent and CLI

First, you need to download the build from the link below:

Releases

The build includes two Java agents, command line tools, a maven plugin, and required dependencies.

Use Java agent standalone to perform runtime checking

• Migration Java version from 8 to 11:

  $ java -javaagent:<path-to-emt4j-build>/lib/agent/emt4j-agent-jdk8-0.8.0.jar=to=11,file=jdk8to11.dat

• Migration Java version from 11 to 17:

  $ java -javaagent:<path-to-emt4j-build>/lib/agent/emt4j-agent-jdk11-0.8.0.jar=to=17,file=11to17.dat

• Migration Java version from 8 to 17:

  $ java -javaagent:<path-to-emt4j-build>/lib/agent/emt4j-agent-jdk8-0.8.0.jar=to=17,file=jdk8to17.dat

• The Java agent will record the compatibility problems found during running into the file. This file is a binary file, you need to transform it to a readable format by the command:

  $ sh <path-to-emt4j-build>/bin/analysis.sh -o report.html <file generated by agent>

Java agent options:

• file : the output file path. The default is emt4j-${yyyyMMddHHmmss}.dat in the current working directory.

• to : the target JDK version.

• priority : the minimum rule priority. p1, p2, p3 and p4 are supported. The default is not set.

Use CLI

The build contains a script named analysis located in the directory bin (.sh is for Mac or Linux users and .bat is for Windows users).

You can use this script to scan compatibility problems that exist in classes, JARS, and directories that contain classes and JARS.

• Migration Java version from 8 to 11:

  $ sh bin/analysis.sh -f 8 -t 11 -o report.html <files...>

• Check JVM options

  $ sh bin/analysis.sh -f 8 -t 17 <file that contains JVM options>

Options:

• -f : the JDK version that the project currently uses. 8, 11 and 17 are supported.

• -t : the target JDK version. 11, 17, 21 are supported.

• -priority : the minimum rule priority. p1, p2, p3 and p4 are supported. The default is not set.

• -p : the report format, HTML, TXT, and JSON are supported. Default is HTML

• -o : the output file name (the default name is 'report').

• -v : print more detailed messages.

Other Documents

Development Guide