Migrating to Jakarta EE 9

In this blog post I will document the way, we at Imixs-Workflow migrated from Java EE to Jakarta EE 9. The Java Enterprise Stack has always been known for providing a very reliable and stable platform for developers. We at Imixs started with Java EE in the early beginnings in the year 2003. At that time Java EE was not comparable to the platform we know today. For me the most impressive part of the journey with Java EE over the last 17 years was the fact, that you can always trust on the platform. Even if new concepts and features where introduced, your existing code worked. For a human-centric workflow engine, like our open source project Imixs-Workflow, this is an important aspect. A workflow engine have to be sustainable. A long running business process my take years from its creation to its final state. An insurance process is one example of this kind of a business process. I personally run customer projects, started running Imixs-Workflow on Glassfish, switched to JBoss, migrated to Payara and run today on Wildfly. Upgrading the Java EE version and switching the server platform was never something special about which you had to write a lot. But with Jakarta EE9 the situation changed dramatically.

Jakarta EE 9 – a New Namespace

The transition from Oracle to the Eclipse Foundation and from Java EE to Jakarta EE takes several years. The reason for the long transition phase is due to the fact, that at Oracle some very clever lawyers came up with the idea to make it as difficult as possible for the software industry. The basic idea was probably: we don’t like Java EE anymore, but at least we leave a lot of scorched earth. But fortunately, lawyers don’t understand much about software development. Thus, although this involves a change in the namespace, the change is not particularly difficult.

The important point is to switch as many projects as possible to Jakarta EE 9 at the same time in order to avoid lengthy migration phases. This was discussed as the Big Bang strategy. So it was also clear for our own project to switch to Jakarta EE 9 relatively quickly.

Now let’s start…

Switching Dependencies

The first thing to do is switching the platform release form Java EE to Jakarta EE 9. In Maven you just have to change the main dependency from:

    <dependency>
	<groupId>javax</groupId>
	<artifactId>javaee-api</artifactId>
	<version>8.0</version>
	<scope>provided</scope>
    </dependency>

into:

    <dependency>
        <groupId>jakarta.platform</groupId>
        <artifactId>jakarta.jakartaee-api</artifactId>
        <version>9.0.0</version>
        <scope>provided</scope>
    </dependency>

I also recommend to update the JDK version. We used Java 8 until Java EE8 and started switching to Java 11 with Jakarta EE 9.

    <plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<version>3.8.1</version>
	<configuration>
		<source>11</source>
		<target>11</target>
	</configuration>
    </plugin>

Now your project will typically no longer compile. The reason is the namespace switch I mentioned above. All packages starting with for example javax.ejb or javax.persistence have to be replaced with the new jakarta prefix. So you have to change the imports of your code base from:

import javax.ejb.*;
import javax.persistence.*;
import javax.servlet.*;
import javax.xml.*;

into:

import jakarta.ejb.*;
import jakarta.persistence.*;
import jakarta.servlet.*;
import jakarta.xml.*;

You can do this job with a shell script. But I think doing the manually can be helpful in a way that you have a short review of your code.

That’s it!

Once you have done the renaming, the hard part of you migration is finished. Running a

mvn clean install

will show you that everything is fine again. In the next section I will give some thoughts about side aspects of the migration to Jakarta EE 9.

JSON & XML Support

If you use a javax.json or jaxb implementation within you codebase – which often is the case for junit tests – you may have dependencies like this one:

  <dependency>
	<groupId>javax.json</groupId>
	<artifactId>javax.json-api</artifactId>
	<version>1.1.4</version>
	<scope>test</scope>
  </dependency>
  <dependency>
	<groupId>org.glassfish</groupId>
	<artifactId>javax.json</artifactId>
	<version>1.1.4</version>
	<scope>test</scope>
  </dependency>

with jakarata EE 9 you have to replace this with the new Glassfish and Jakarta implementation of json and jaxb:

  <dependency>
      <groupId>org.glassfish</groupId>
      <artifactId>jakarta.json</artifactId>
      <version>2.0.0</version>
      <scope>test</scope>
  </dependency>
  <dependency>
      <groupId>org.glassfish.jaxb</groupId>
      <artifactId>jaxb-runtime</artifactId>
      <version>3.0.0</version>
      <scope>test</scope>
  </dependency>
  <dependency>
      <groupId>jakarta.xml.bind</groupId>
      <artifactId>jakarta.xml.bind-api</artifactId>
      <version>3.0.0</version>
      <scope>test</scope>
   </dependency>

Switching from Nashorn to GraalVMJS

As our project Imixs-Workflow is a BPMN based workflow engine we have of course to deal with a lot of business logic which is part of the workflow model. Therefore we used the script engine Nashorn to evaluate JavaScript based business rules at runtime. But Nashorn will no longer be maintained in the future so you will see deprecation warnings in newer application severs when using Nashorn. The good news is, that there is already a very powerful successor – the GraalVMJS. This scripting framework is part of the GraalVM (introduced by Oracle) and can be used in combination with Jakarta EE even if you do not run your code on Graal VM. To add support of GraalVMJS just add the following maven dependency:

  <dependency>
	<groupId>org.graalvm.js</groupId>
	<artifactId>js</artifactId>
	<version>20.2.0</version>
  </dependency>  
  <dependency>
	<groupId>org.graalvm.js</groupId>
	<artifactId>js-scriptengine</artifactId>
	<version>20.2.0</version>
  </dependency>	

The GraalVM scripting engine has a lot of advantages in compare to the Nashorn engine. It does not only allow you to run JavaScript but also many other languages like Python, Ruby, R, JVM-based, and LLVM-based languages. There a some good bog postings here and here helping me to do the migration.