Enabling Jakarta EE 9 for development and test by using the Eclipse Transformer

In this post, we describe how to use the Eclipse Transformer to update your applications and test artifacts for Jakarta EE 9. We also describe the steps to update Open Liberty server configurations to run Jakarta EE 9 applications.

The core problem that is introduced by Jakarta EE 9 is the renaming of package prefixes from javax to jakarta for APIs and properties. As a consequence, existing applications that run against Java EE 7 or Jakarta EE 8 do not run against Jakarta EE 9. To run existing applications as Jakarta EE 9 applications, specific package references must be updated.

To solve this problem, the Open Liberty development team created the Eclipse Transformer. This open source project provides a utility that updates package references in various artifacts.

The development team uses the Eclipse Transformer to update bundle implementation archives. The team also uses the transformer to update test artifacts, including applications, test classes, and Open Liberty server configurations.

Similarly, you can use the Eclipse Transformer to update applications, test classes, and server configurations. Updates to applications and test classes are usually necessary. Updates to server configurations are necessary when using Open Liberty.

The transformer is quick and efficient. When integrated as a build step, as is done in Open Liberty builds, using the transformer avoids the creation of new Jakarta EE 9 source files.

Although this post focuses on updating from Jakarta EE 8 to Jakarta EE 9, the same information holds true for updating from Java EE 7 to Jakarta EE 9.

To transform test artifacts, package references must be updated to change old javax package references into new jakarta package references. Package references can be in several locations, including test applications, test code, and server configurations.

Additionally, in Open Liberty, server configurations must be updated to replace old Jakarta EE 8 features with corresponding new Jakarta EE 9 features. Currently, the transformer does not have the rules data necessary to specify feature name updates. These updates must either be made manually, through custom code, or by creating new rules data for the transformer. For more information about updating Open Liberty features, see Updating Open Liberty features in server configurations.

A transformer image can be obtained either by downloading the image or by building an image by using the open source repository.

Alternatively, the transformer can be built by cloning the Eclipse Transformer repository and invoking maven to build the transformer JAR file:

The maven build creates the distribution JAR file at:

Unzipping the downloaded or built distribution obtains the transformer and prerequisite JAR files:

The Eclipse Transformer can be run directly from the command line, as a Gradle task, or from Java code. This post describes using the transformer from the command line. For more information, see the transformer project pages.

To run the transformer by using the default rules, run the following command:

The target location can be a packed application archive file (EAR, WAR, RAR, or JAR) or a directory that contains the fully or partially expanded contents of one of these archives. The target can also be a directory that contains Java source, or a directory that contains several application archives. It can even be a single file, such as a server.xml file. The transformer processes all of the artifacts in the target location. Transformed artifacts are written to the output location.

The org.eclipse.transformer.cli-0.3.0-SNAPSHOT.jar file is a runnable JAR file that specifies org.eclipse.transformer.jakarta.JakartaTransformer as the main class and uses the necessary JAR files from the libs folder in its class path.

You can run the transformer using custom rules by specifying options on the command line. The additional options specify local rules files that the transformer uses instead of the default rules files.

For example, to use Open Liberty rules data, which can be more up to date than the default rules data, download Open Liberty Rules. Then, pull in the downloaded rules data by adding options -tr, -td, and -tf, to the command-line invocation:

The -tr option specifies a properties file that contains package rename data. The -td option specifies a properties file that contains java direct string replacement data. The -tf option specifies a main properties file that links to other properties files. Each of the linked properties files contains replacement data for text-like files that match specific patterns, as specified in the main properties file.

These three command-line options are most important for application and test developers. Other command line options are available, but are less important. For example, the option -tb is used to specify data for transforming bundle archives, while the option -ts is used to specify which target files are to be transformed. For more information about command-line options, run the transformer with either the -usage option or with the -help option.

For Jakarta EE 9 applications to run in Open Liberty, new Jakarta EE 9 features must be specified in the server configuration. In many cases, the new Jakarta EE 9 features use the same short names as the corresponding Jakarta EE 8 features. In those cases, the Jakarta EE 9 features simply have an updated feature version. For example, cdi-2.0 was updated to cdi-3.0. However, in some cases, the feature short name is also different, as with ejb-3.2, which was updated to enterpriseBeans-4.0.

If an old short name is incorrectly used with a new Jakarta EE 9 version, the server does not start, and the server logs provide information to say which new feature short name must be used. For example, if ejb-3.2 is incorrectly changed to ejb-4.0, the server logs indicate that enterpriseBeans-4.0 must be used.

Currently, the transformer cannot update Open Liberty features because it is missing rules data to specify the updates. Features must be updated manually or by custom code.

The following table lists features for which only the feature version is updated:

The following table lists features for which both the feature short name and the feature version are updated: