Updating Your Applications to Jakarta EE 10

Updating to Jakarta EE 10 from an older version can be tricky but rewarding. Broadly, it can be broken down into three steps:

• Ensuring existing codes and libraries are compatible, which requires updating references to the javax package prefix to the jakarta prefix
• Replacing obsolete annotations 
• Rewriting code that uses removed APIs

This process applies to both your codebase and your dependencies. While it’s a process that can be done manually, it’s much easier to leverage an automated tool to do the most of it. Free tools such as Openwrite or Eclipse Transformer can automatically make changes to an application’s source code and convert over references. On top of that, the Eclipse Transformer can automatically transform existing JAR, WAR, or EAR files.

Some libraries, however, will depend on APIs that have been removed. Here, it’s possible to replace the library with another, compatible library, or to transform it to not be reliant on those APIs. 

Here’s a high-level breakdown of the steps involved, some of the best tools to use, and some tips and tricks to keep in mind as you undergo the process. 

Using Eclipse Transformer to Update References

The first step of the process requires updating your references, and by far the easiest way to do this is by using the Eclipse Transformer. It makes a great starting point because it tells you whether your application needs any changes to be migrated. It scans your binary, modifies the bytecode, updates resources, and transforms nested JAR files as well. The transformed application should work with Jakarta EE 10, unless it relies on features that have been dropped. This not only makes the transformer a great way to start but an excellent way to troubleshoot a transition.

Using the Eclipse Transformer on the command line without adding any Maven plugin or configuration will usually result in compatible source code if you don’t have any third-party dependencies. However, if your application does rely on any third-party dependencies or APIs that have been renamed or removed, you’ll need to do some more work. 

Update or Transform Libraries

For the most part, libraries in your application will either not use Java APIs at all or they’ll have a newer version compatible with Jakarta EE 10 and will just need to be updated. Sometimes the library doesn’t have a compatible version and can’t be updated, and so must be transformed. 

Most libraries already support Jakarta EE 10, so you’ll simply need to change the version number. For the Hibernate library, for example, updating to version 6.2.7, the latest version, looks something like this:

<dependency>
  <groupId>org.hibernate.orm</groupId>
  <artifactId>hibernate-core</artifactId>
  <version>6.2.7.Final</version>
</dependency>

However, libraries that support both older versions of Jakarta EE and Java EE with the javax package prefix and a newer version of Jakarta EE with the jakarta package prefix will need an additional Jakarta classifier or a different artifact name in the dependency definition to ensure the correct variant is downloaded.

For libraries that need to be transformed, there’s a trick. Maven and Gradle-based libraries rely on transitive dependencies, which makes our transformation more complicated. To get around it, merge all the JARs that need to be transformed into one JAR with all the transitive dependencies, transform the JAR, then install it into a Maven repository. Once that’s done, you can simply change the application to depend on this single artifact. 

Resources and Guides Available

This brief breakdown should give you a high-level understanding of the steps involved in making the switch to Jakarta EE 10. But, of course, there’s going to be a fair amount of nitty-gritty effort, which will differ by application and library. 

Fortunately, there’s plenty of resources available. For a more comprehensive breakdown of the full process, including how to tackle individual steps, OmniFish has a four-part series showing how to make the transition, with more steps to come (including how to refactor code or adjust libraries that rely on removed APIs.)

There’s also a repository available that breaks down how to upgrade some existing applications, which can be found here. And there are examples available of how to transform from Jakarta EE 8 to Jakarta EE 10 here.