Jakarta EE8, EE9, EE9.1, …. What???

Jakarta EE is the new Java Enterprise platform as you’ve probably heard. There is a lot of news about this application development framework and also about the rapid development of the platform. Version 9.1 was released in May last year and version 10 is already in a review process. But what does this mean for my own Java project? Because I was also a bit confused about the different versions, hence my attempt to clarify things.

First, the good news: As an application developer, you don’t have to worry. The most important thing that will change besides improved support by the community is the Java package names. The package name javax.* will be replaced by jakarta.*.

Jakarta EE8

Jakarta EE8 was the first release after the Eclipse foundation overtook the project from Oracle. Nothing but the name has changed. Your existing Java EE8 projects will work out of the box. In your Maven dependencies, you can now use the new Jakarta EE8 platform reference.

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

Jakarta EE9

The Jakarta EE9 project is something that as an application developer you can generally ignore. The goal of Jakarta EE 9 was the namespace change from javax.* to jakarta.*. It is more an intermediate release so tools and libraries can get their support for the Jakarta.* namespace done. Only in case you want to test your own code against the new namespace, the change of the release version is relevant. You just need to change your Maven dependency.

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

But for normal application development, Jakarta EE9 brings no special changes. Since the namespace change behind the scenes is very complex, this release was necessary for platform and library developers.  

By the way, most of the application servers will do the namespace migration for you during deployment. So as an application developer you can still use the javax.* namespaces, even if your target runtime will be Jakarta EE9. This means your ‘old’ application using the javax.* namespace will be running fine on newer Jakarta EE severs. 

/* Jakarta EE8 */
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("api")
public class BaseApplication extends Application {

}

On the other hand, if you want to try to develop against the new jakarta.* namespace your code changes like this:

/* Jakarta EE9 */
import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("api")
public class BaseApplication extends Application {

}

Note: Applications using the jakarta.* namespace will only work on fully compatible Jakarta EE9 servers (e.g., wildfly-preview-26.0.0). Most of the official Jakarta EE servers are still on Jakarta EE 8. So from the perspective of an application developer, it currently makes no sense to switch to the new namespace. 

Jakarta EE9.1

The Jakarta EE9.1 project is similar to Jakarta EE9 just an intermediate release. The difference between Jakarta EE 9 and 9.1 is the JDK 11 support. It wasn’t supposed to be two versions, but the Jakarta EE project ran a little out of time to support the TCK JDK 11. Therefore, this has been moved to an additional version now known as 9.1.

So again, as an application developer, you can ignore this detail. Just your Maven dependency should force JDK 11 in case you want to build against Jakarta EE 9.1:

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>
    <dependency>
        <groupId>jakarta.platform</groupId>
        <artifactId>jakarta.jakartaee-api</artifactId>
        <version>9.1.0</version>
        <scope>provided</scope>
    </dependency>

Jakarta EE10

So Jakarta EE 9 was released to prepare projects (mostly library and tool vendors) for the namespace change. As an application developer, you can go ahead with the old namespace javax.* (which I recommend for now). Jakarta EE 10 will then become the first version switching the namespace for all included libraries. This means if Jakarta EE10 is out, you can safely switch your own application from the javax.* namespace to the jakarta.* namespace.  But as for now, no official server is available you can wait with this. 

Switching the Namspace

If you plan to switch the namespace later for your project to Jakarta.* read my blog post. You can simply run a bash script against your source code like this one:

#!/bin/bash

# this script can be used to replace deprecated javax. package names from a 
# Java EE8 project with the new jakarta. package names in Jakarta 9
# Initial version from rsoika, 2021

echo "replacing:"
echo "    javax.annotation.  -> jakarta.annotation."
echo "    javax.ejb.         -> jakarta.ejb."
echo "    javax.enterprise.  -> jakarta.enterprise."
echo "    javax.faces.       -> jakarta.faces."
echo "    javax.inject.      -> jakarta.inject."
echo "    javax.persistence. -> jakarta.persistence."
echo "    javax.ws.          -> jakarta.ws."
echo "Replacing now..."

###################
## REPLACE LOGIC ##
###################

# replace package names...
find * -name '*.java' | xargs perl -pi -e "s/javax.annotation./jakarta.annotation./g"
find * -name '*.java' | xargs perl -pi -e "s/javax.ejb./jakarta.ejb./g"
find * -name '*.java' | xargs perl -pi -e "s/javax.enterprise./jakarta.enterprise./g"
find * -name '*.java' | xargs perl -pi -e "s/javax.faces./jakarta.faces./g"
find * -name '*.java' | xargs perl -pi -e "s/javax.inject./jakarta.inject./g"
find * -name '*.java' | xargs perl -pi -e "s/javax.persistence./jakarta.persistence./g"
find * -name '*.java' | xargs perl -pi -e "s/javax.ws./jakarta.ws./g"

echo "DONE!"