Upgrade to Jakarta EE 10 – part 1: Transform Applications with Eclipse Transformer

As we described in the introductory article, migrating your existing Java EE 8 or Jakarta EE 8 applications to Jakarta EE 10 can be streamlined by a few existing tools. In this article, we’ll explore the first crucial step in upgrading to Jakarta EE 10: using the Eclipse Transformer to transform your final binary application so that it can be deployed to a Jakarta EE runtime like Eclipse GlassFish 7.

Why Use Eclipse Transformer? Whether you have a pre-packaged application or you want to swiftly migrate your project to build it for a Jakarta EE 10 runtime, Eclipse Transformer is your go-to tool. This powerful utility scans your final application binary (e.g. WAR or EAR), modifies the Java bytecode, and updates the resources to refer to the correct packages. It automatically transforms nested JAR files as well, ensuring comprehensive package replacement. By doing so, your final application binary will rely on Jakarta EE 10 APIs, making it compatible with Jakarta EE 10 runtimes, provided it doesn’t employ any obsolete functionalities dropped in Jakarta EE 10.

We recommend starting every migration with Eclipse Transformer so that you can quickly verify whether your application can be migrated to a Jakarta EE 10 runtime without changes or identify potential problems for the migration. Using Eclipse Transformer might also be essential in later stages of your migration, especially if your application relies on dependencies that are not yet compatible with Jakarta EE 9+ or if it’s risky to upgrade them to a compatible version. In the end, transforming your application with Eclipse Transformer before you deploy it to a Jakarta EE 10 runtime can work as a safety net, detecting and transforming any remaining classes and files that depend on older API packages. You can keep using Eclipse Transformed until you’re absolutely sure everything in your application has been migrated.

Configuring Eclipse Transformer with Maven projects

To demonstrate the ease of using Eclipse Transformer, we’ve prepared a sample application project at javax-jakarta-transform-whole-war. This project showcases how to apply Eclipse Transformer into the build of a Maven project. By configuring Eclipse Transformer with this project, you can transform the final WAR artifact and the exploded WAR directory. The benefits are manifold:

• You can deploy the transformed final WAR file to a Jakarta EE 10 runtime using the usual deployment mechanisms.
• IDEs that support deploying exploded directories will also seamlessly deploy the transformed application to the configured Jakarta EE 10 runtime.
• The transformed WAR artifact, when deployed to a Maven repository, remains compatible with Jakarta EE 10 runtimes.
  • This means that if you want to deploy the artifact downloaded from the Maven repository at a later stage, you won’t need to modify it again to match your Jakarta EE 10 runtime.

The key ingredient to applying the transformation in a Maven project is the Maven plugin transformer-maven-plugin. This plugin can be installed as an extension, and then it can hook into the standard Maven build mechanism and modify the final build artifact.

The Maven plugin provides two goals:

• jar – this goal transforms application packages, like JAR, WAR and EAR files. It can either modify them in place, or create their transformed version in a separate file
• transform – this goal transforms directories (before they are packed into JAR, WAR or other application packages). It can be used on exploded directories before they are deployed to an app server

In our example application, we use both plugin goals. The jar goal is used to transform the final artifact file, which is required to deploy the file later or deploy it to a Maven repository. The transform goal is optional and is used to transform the exploded directory, which is often used during development by various IDEs to deploy the application. Using the transform goal is optional but makes it easier to develop the application until it is fully migrated to Jakarta EE 10 and Eclipse Transformer is needed no more.

To include the plugin into your project, add the following plugin definition to the pom.xml file:

<plugin>
    <groupId>org.eclipse.transformer</groupId>
    <artifactId>transformer-maven-plugin</artifactId>
    <version>0.5.0</version>
    <extensions>true</extensions>
    <configuration>
        <rules>
            <jakartaDefaults>true</jakartaDefaults>
        </rules>
    </configuration>
</plugin>

This adds the plugin as an extension (required to modify the final artifact) and applies the default rule to convert the files and packages renamed in Jakarta EE 9.

Then add an execution for the jar goal, which defines the current project’s main artifact as the artifact to transform:

 <execution>
    <goals>
        <goal>jar</goal>
    </goals>
    <configuration>
        <artifact>
            <groupId>${project.groupId}</groupId>
            <artifactId>${project.artifactId}</artifactId>
        </artifact>
    </configuration>
</execution>

This execution runs in the package phase (the default phase for the jar goal of the transformer plugin), and it transforms the main artifact right after it’s built. As a result, the final artifact, which would normally depend on older Jakarta EE 8 APIs, is now fully compliant with Jakarta EE 9 APIs.

Finally, to simplify the development, we also add an execution for the transform goal:

<execution>
    <phase>package</phase>
    <goals>
        <goal>transform</goal>
    </goals>
    <configuration>
        <transformDirectory>${project.build.directory}/${project.build.finalName}</transformDirectory>
    </configuration>
</execution>

This execution needs to run in the package phase, after the built-in Maven war or ear plugins prepare the exploded application directory. The transformer will then transform this directory, which is usually in the ${project.build.directory}/${project.build.finalName} location.

As a result, if an IDE deploys the application from the exploded directory, it’s already transformed and can be deployed to a Jakarta EE 10 runtime.

To see the full working project, check out the source code here: javax-jakarta-transform-whole-war.

Configuring Eclipse Transformer without Maven

Besides using it as a Maven plugin, Eclipse Transformer can be also used on command line and thus with any project or a continuous integration system. The main difference in functionality is that it never modifies the input application package or exploded folder in place, it always creates a transformed copy. If you want to transform the original file or folder, you need to ensure that you replace the original file or folder with the transformed one afterwards. Another difference is that you can execute the transformer on a file or an exploded directory with the same configuration, no need to execute a different goal as with the Maven plugin.

To run Eclipse Transformer on command line, first download the org.eclipse.transformer.cli distribution JAR file from Maven Central. Then unpack this JAR, for example into a folder named transformer. Then you can transform your application file jakarta-ee-8-app.war into a new application file jakarta-ee-10-app-transformed.war with the following command:

java -jar transformer/org.eclipse.transformer.cli-0.5.0.jar jakarta-ee-8-app.war jakarta-ee-10-app-transformed.war

You can find more information on how to use Eclipse Transformer on command line on the Github project. However, in most case, you wouldn’t need anything else, the tool does a very good job even with the default options.

Conclusion

By using the Eclipse Transformer tool, you can make the process of transforming your existing Java EE 8 or Jakarta EE 8 application into a Jakarta EE 10 application easier and faster. Your transformed application may not yet fully work with Jakarta EE 10 if it relies on the obsolete features that were dropped. Nevertheless, using Eclipse Transformer is an important first step in the migration to Jakarta EE 10. It allows you to deploy and test your application on a Jakarta EE 10 platform right away and gradually transition it to a native Jakarta EE 10 application. It also helps you identify if your application depends on any features that have been removed and it needs to be updated. In upcoming articles, we’ll discuss further migration steps towards full migration to Jakarta EE 10.

Series Navigation

<< How to upgrade to Jakarta EE 10 and GlassFish 7 – it’s much easier than you think!Upgrade to Jakarta EE 10 – part 2: Transform Application Source Code >>