Jakarta EE 9 with WildFly Preview

The large majority of the libraries included in WildFly Preview that were compiled against EE APIs were based on the javax.* EE 8 APIs. This includes the libraries produced from WildFly’s own code base and by WildFly Core. But the EE APIs libraries available in the WildFly Preview runtime all use the jakarta.* packages. How can this work?

The solution we’ve come up with for this is to provide a new 'wildfly-preview' Galleon feature pack, in addition to the standard 'wildfly' feature pack. (Recall that any WildFly server installation, including the ones that are zipped up and made available for download here, is produced by telling Galleon tooling to provision from a feature pack.) The 'wildfly-preview' feature pack differs from the standard 'wildfly' one in a number of ways, with the key ones relevant to EE 9 being:

The last item is the key point. When Galleon provisions a 'wildfly-preview' server by pulling jars down from maven, it knows that some artifacts were compiled against EE 8 javax.* packages. So it bytecode transforms those jars to alter references to EE 8 packages in the class file constant tables to change from javax.* to jakarta.*. The transformation goes beyond simple package renames; a number of other known differences between EE 8 and EE 9 are handled. We owe a great deal of thanks to B.J. Hargrave and the community behind the Eclipse Transformer project for their work on the underlying transformation tool.

You can use the Galleon CLI tool to provision a server from the wildfly-preview feature pack yourself:

Note the use of 'wildfly-preview' instead of 'wildfly'. Because this release is an alpha, Galleon won’t try to install it by default if you don’t give it explicit instructions to do so. So I include the '#22.0.0.Alpha1' in the feature pack location string. Another way to do this is to explicitly state that an alpha feature pack frequency is acceptable:

As Galleon provisions the server it will log quite a bit of information about the transformation work it is doing.

Please note that the transformation adds a fair bit to the amount of time it takes to provision the server.

The APIs that WildFly Preview exposes to deployments are the EE 9 APIs, so all the classes and interfaces are in the jakarta.* packages. But what if you want to run an existing EE 8 application on WildFly Preview? We expect that to be a very important use case in the long run. Eventually the jakarta.* APIs will be what’s provided by the standard WildFly distribution, but many WildFly users will have existing applications that they’ll want to continue to run unchanged. So we wanted to make sure from the very beginning that that works.

What we’ve done is we’ve added to the server’s handling of managed deployments the same basic transformation that’s applied to the server artifacts when provisioning. A managed deployment is one where a management client (the CLI, HAL console or the deployment scanner) presents deployment content to the server and the server makes a copy of it in its internal deployment content repository. The content that gets installed into the runtime is that internal copy.

A WildFly Preview server, when it reads in deployment content to store in the content repository, will transform any EE 8 content into EE 9.

In the long run I feel it’s better for users if they either convert their application source to EE 9 APIs, or use build-time tooling that we and the rest of the Jakarta community will work to provide to do transformation at build time. But some applications just can’t be changed, so the server-side solution we’re using can handle those cases.

Confession: beyond wanting to make sure EE 8 deployments can run for users, we need it to work for ourselves. The WildFly testsuite is full of hundreds of EE 8 deployments. We want to be able to run those tests aganst WildFly Preview, so we needed to make this work.