Jakarta EE 9 with WildFly Preview

I’m pleased to announce that the WildFly 22 Alpha1 zips are now available for download. This includes the first release of a new 'WildFly Preview' distribution of WildFly, which we’re using to give our community a tech preview look at things we see coming down the road in our main WildFly distribution. Right now this is mostly about what we are doing with Jakarta EE 9, although there are some other differences that I’ll get into below.

We don’t normally do alpha releases of WildFly, but we’re overdue to give our community a look at what we’re doing on EE 9. I believe what we have can be a useful milestone for people wanting an early look at where we’re going, so here it is!

WildFly Preview and Jakarta EE 9

It’s exciting to see the great progress the Jakarta EE community has made on the way to the upcoming GA release of Jakarta EE 9!

As I discussed in my June post on the plans for WildFly and EE 9, the EE 9 release is primarily about implementing the necessary change in the Jakarta EE APIs from the javax.* package namespace to the jakarta.* namespace. This is a big change that is going to take a while to percolate through the EE ecosystem, e.g. for the many projects that compile against the EE APIs to provide versions that use jakarta.*. While this happens we want to continue to deliver new features and fixes to our community, so the primary WildFly distribution will continue to provide the EE 8 APIs.

But, we want the community to begin to look at EE 9, so we decided to produce a new distribution of WildFly, which we’re calling WildFly Preview. With WildFly 22 Alpha1 we’re providing the first download of WildFly Preview.

EE 9 Via Bytecode Transformation and the 'wildfly-preview' Galleon Feature Pack

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:

  • Where suitable EE 9 spec API jars were available from Eclipse, those were used instead of the EE 8 spec jars used in standard WildFly.

  • Where suitable 'native' EE 9 implementation libraries (i.e. ones compiled against jakarta.*) were available, those were used. This includes Weld, Hibernate Validator, Mojarra, Yasson, Jakarta EL and Jakarta JSON.

  • Any libraries that were using EE 8 APIs were detected and instructions were incorporated in the feature pack telling Galleon to do byte code transformation of that library whenever it provisions a server using the feature pack.

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:

galleon.sh install wildfly-preview:current#22.0.0.Alpha1 --dir=my-wildfly-server

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:

galleon.sh install wildfly-preview:current/alpha --dir=my-wildfly-server

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.

WildFly Preview Support for EE 8 Deployments

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.

Other Differences in WildFly Preview

Besides exposing EE 9 APIs, we want to use WildFly Preview to help get community exposure for other changes we plan to make in the server. Here are the key ones:

  • The legacy security subsytem is not supported. The standard configurations are all based on Elytron security. Our goal is to remove the underlying Picketbox libraries altogether in the next few months. This is an important prerequisite for supporting JDK 14 or later. When we do this, security vault support will be removed as well. Elytron credential stores should be used.

  • The security vault tool (used to manipulate vault contents) is not provided.

  • The standard configuration files do not configure an embedded messaging broker. Instead they configure the 'messaging-activemq' subsystem to provide connections to a remote ActiveMQ Artemis broker. (It’s a task for the user to run such a broker or to update the config to integrate with a different broker.) We want WildFly out-of-the-box to be more of a cloud native appserver and having an embedded messaging broker in the default configuration is not cloud native. A WildFly container in the cloud running an embedded broker is not scalable, as multiple broker instances need separate configuration to act as a primary or backup. An embedded messaging broker also has more advanced persistent storage requirements than a server primarily dedicated to handling HTTP requests would have. Note however that running an embedded broker is still supported. We’ve added an example 'standalone-activemq-embedded.xml' configuration showing its use to the $WILDFLY_HOME/docs/examples/configs folder.

  • The Picketlink extension is removed.

  • The JSR-77 extension is removed.

  • The extensions providing the legacy subsystems 'cmp', 'config-admin', 'jacorb', 'jaxr', 'messaging' (HornetQ based), and 'web' (not 'undertow') are removed. These were only used for domain mode to allow a Domain Controller to control hosts running much earlier WildFly versions where servers using these subsystems were supported.

Known Issues

Please understand that WildFly Preview is a true alpha, so you may find issues if you try it for your use case. If you do, please report them on the WildFly JIRA.

There are a number of known issues:

  • WildFly Preview does not pass the EE 9 platform TCK. We currently have 193 failures (out of over 40,000 tests). These are mostly in the webservices area.

  • The bootable jar feature we’ve been rolling out over the last few WildFly releases does not support WildFly Preview yet.

  • JBoss Modules modules installed by the user are not transformed. If such a module uses EE 8 APIs it will not work.

  • Deployment overlays are not transformed. So any overlay artifact that uses EE 8 APIs will not work.

  • Unmanaged deployments that use EE 8 APIs will not work. We transform managed deployments when we copy the deployment content into the internal content repo. For unmanaged deployments we use the original content file(s) the user provides, and WildFly won’t modify those files as we don’t consider them as being 'owned' by the server.

  • Managed exploded deployments likely won’t work.

  • Applications incorporating the EE 9 variant of the Jakarta XML Web Services WSDL customization descriptor will not work. The EE 8 variant, which should be semantically equivalent, should work.

  • Alternate JPA and JSF providers that you can install with standard WildFly are not supported.

Note that the current lack of support for parsing EE 9 WSDL customization descriptors means our test coverage of EE 9 Jakarta XML Web Services applications is less robust than it is for most other EE technologies.

Looking Forward

The near term priorities for WildFly Preview are to continue to progress on the EE 9 TCK and to get bootable jar support working. We’ll strive to continue to improve the speed of the transformation process. And as more 'native' EE 9 variants of the libraries we use become available we’ll update WildFly Preview to incorporate those.

Later on we’ll work to handle transforming deployment overlays and perhaps to handle JBoss Modules modules added by the user.

Jira Release Notes

The full list of issues resolved is available here. Issues resolved in the WildFly Core 14 Beta1 release included with WildFly 22 are available here.


We hope you enjoy WildFly 22 Alpha1. Please give it a try, particularly WildFly Preview, and give us your feedback. But most important, please stay safe and well!