Upgrading to Jakarta EE 9

In the Jakarta EE 9 Milestone Release Party, the Jakarta team shared the latest work from Eclipse EE4j project.

Update: Jakarta EE 9 is already released. A small update to this post:

• The original Java 11 compatibility constraint is remove in Jakarta EE 9 spec.
• Glassfish v6 still only supports Java 8.

• The Jakarta EE platform API is close to be public, currently it targets 9.0.0-RC2.
• Glassfish v6 M1 is released.
• Eclipse Transformer tooling helps you to transform the existing Jakarta EE 8 codes to Jakarta EE 9.

You can also read Jakarta EE is taking off from the official Eclipse blog to know more details about the current status of the Jakarta EE 9 specification and Eclipse EE4j project.

What is new in Jakarta EE 9

No panic, there are almost no new features added in Jakarta EE 9, but it will bring breaking changes in your codes if you are upgrading from Jakarta EE/Java EE 8.

• All javax.* prefix in the package names are changed to jakarta.*.
• All XML namespaces in the deployment descriptor files(such as web.xml, beans.xml, etc) are changed to https://jakarta.ee/xml/ns/jakartaee
• The versions of all specs jump to the next main version, eg. CDI 2.0->3.0.
• Some specs are marked as pruned in Jakarta EE 9, such as the old XML-RPC, etc. More details please got to 6.1.4. Removed Jakarta Technologies of the official Jakarta EE specifications. You should avoid these specs and use the newest replacement in your new projects.
• Some specs are marked as Optional in Jakarta EE 9, such as the traditional SOAP based Web Services related specs, please check 6.1.3. Optional Jakarta Technologies section for more details. If your want to use these specs in your new projects, you have to consult the document of the Jakarta EE 9 provider you are using, and make sure they are supported in the new version.
• The APIs of Jakarta EE 9 is still stick on Java 8, [but all compatible products(implementers) should be compatible with Java 11 at runtime] Update: Jakarta EE 9 remove this Java 11 constraint.

Upgrading to Jakarta EE 9

Currently the Jakarta EE product vendors are busily moving to the new Jakarta EE 9 platform.

• Currently Glassfish v6.0.0.M1 is available for testing Jakarta EE 9.
• WildFly 21 and Payara platform 6 will provide compatible products in the next months.
• Open Liberty 20.0.0.7 beta provided partial web application support of Jakarta EE 9.
• Jetty 11.0.0-alpha0 and Apache Tomcat 10.0-M6 announced Servlet support of Jakarta EE 9 in their new milestone products.

Eclipse transformer tooling project provide utilities (cli, maven plugin ) to help your upgrade the codes in batch mode, currently Jakarta EE 9 rules is under development.

Another tool — tomcat-jakartaee-migration is from Apache Tomcat project, which is also used to handle the changes of naming rules automatically when migrating to Jakarta EE 9 platform.

Here we will use Glassfish v6.0.0.M1 as target runtime , and manually upgrade my former Jakarta EE 8 starter to Jakarta EE 9 platform.

Note : Unfortunately, Glassfish v6.0.0.M1 still requires Java 8 at runtime. Java 11 support will be added in the next milestones.

Getting Glassfish v6.0.0.M1

Download Glassfish v6.0.0.M1, extract files into your discs.

Open your terminal, and enter the glassfish6/bin folder, and start up Glassfish manually by executing the following command.

asadmin start-domain domain1

Clean up the Jakarta EE 8 codes

As an example, we will use existing Jakarta EE 8 starter here.

• Get a copy of Jakarta EE 8 starter, and import it into your favorite IDE.
• Open pom.xml file, change the value of jakartaee-api.version property to 9.0.0-RC2, then update your dependencies.
• Open all Java files, replace all java. prefix with jakarta. in the import clauses.
• Open src/main/resources/MATA-INF/beans.xml, change xml namespace to https://jakarta.ee/xml/ns/jakartaee and version to 3.0.

Here I described the steps of manual upgrade, when the Eclipse Transformer project becomes mature, maybe I will introduce it in another post.

Running the application

Make sure you are using Java 8 at the moment. We will switch to Java 11 by default when Glassfish v6 is ready for Java 11. Other providers are compatible for Java 11 for a long time.

• Run the following command to package the application into a war.

mvn clean package

• Copy target/jakartaee9-starter-boilerplate.war to glassfish6/glassfish/domains/domin1/autodeploy folder. The war archive will be tracked by Glassfish and deploy it automatically. When it is done there is jakartaee9-starter-boilerplate.war_deployed generated in the same folder.
• Test the sample endpoints by curl command.

curl http://localhost:8080/jakartaee9-starter-boilerplate/api/greeting/JakartaEE
{"message":"Say Hello to JakartaEE at 2020-06-24T15:45:43.771"}

• To undeploy the application, just remove it from glassfish6/glassfish/domains/domin1/autodeploy folder, when it is done, a jakartaee9-starter-boilerplate.war_undeployed file is generated instead of the former jakartaee9-starter-boilerplate.war_deployed.
• To stop Glassfish v6, enter glassfish6/bin, and run asadmin stop-domain domain1.

Staying informed

I will keep updating this sample project as the related products is coming to the Jakarta EE 9 support, eg.

• Adding WildFly, Open Liberty, Payara Server support back
• Refreshing the Arquillian testing codes when it is ready for Jakarta EE 9
• Updating the configuration of cargo maven plugin and other maven plugins to manage the latest application servers.

And do not forget track the latest news of Jakarta EE from the official Jakarta EE website.