Jakarta EE support

We're thrilled to announce a significant milestone for our JEE platform. Support for Jakarta EE is now available! Our JEE platform expanders now target Java EE 7-8 or Jakarta EE 10.

Releases

At this time, the full support for Jakarta EE is not yet available in beam releases. For migrating expanders and testing until the time that these releases make it into the beams, we've provided developer previews that mirror the beams, but contain the latest versions of all expansion resources.

Expansion resource	Version	Description
net.democritus.preview:minimal-jee-dev-preview	1.1.0	A mirror of the minimal-jee-beam.
net.democritus.preview:standard-api-dev-preview	1.1.0	A mirror of the standard-api-beam.
net.democritus.preview:service-api-dev-preview	1.0.1	A mirror of the service-api-beam.
net.democritus.preview:process-automation-dev-preview	1.0.0	A mirror of the process-automation-beam.

Warning

The dev previews are not intended for use in projects. While we try to do thorough automated testing of these releases to ensure stability, we do not offer the same guarantees as with the beams. The content may also be subject to change by the time the next release of a beam arrives. While these releases may contain the same elements as the corresponding beams, they are synced back up to the structure of the beams whenever a release of the beam occurs.

The goal of these previews is to provide a resource that can be used to test upcoming functionality ahead of time in case there are new features or changes that a project may want to prepare for ahead of time. One such example is the migration to Jakarta EE, where the migration path may require extra effort for some projects.

Preparing your expander project

Expander projects may require some updates if they expand code with javax imports. The first step would be to migrate those specific expanders to the new imports system.

When moving the imports to the mapping file, they should be redefined as the new jakarta imports. The imports as defined in the mapping should be considered the optional/default case:

ExpanderMapping.xml

<?xml version="1.0" encoding="UTF-8" ?>
<mapping xmlns="https://schemas.normalizedsystems.org/xsd/expanders/2025/0/0/mapping" strict="true">
  <artifact this="dataElement.packageName + '.' + dataElement.name + 'ImportantBean'" importStrategy="java"/>

  <uses eval="'jakarta.servlet.http.HttpServletRequest'"/>
  <uses eval="'jakarta.servlet.http.HttpServletResponse'"/>
</mapping>

In addition, it will be required to add a technology lexicon to map the imports back to the old javax equivalent. This in essence allows you to define how the imports should be rewritten if a specific technology is active in the model. Note that these are defined as data resources and will be inherited from dependencies. Many imports may already remap automatically if you depend on a resource such as Expanders that had its own technology lexicon.

javaee-classes.xml

<dataResource type="expansionControl::TechnologyLexicon">
<technologyLexicon>
  <technology name="JAVA_EE"/>
  <coordinateRedirections>
    <coordinateRedirection>
      <coordinate>jakarta.servlet.http.HttpServletRequest</coordinate>
      <target>javax.servlet.http.HttpServletRequest</target>
    </coordinateRedirection>
    <coordinateRedirection>
      <coordinate>jakarta.servlet.http.HttpServletResponse</coordinate>
      <target>javax.servlet.http.HttpServletResponse</target>
    </coordinateRedirection>
  </coordinateRedirections>
</technologyLexicon>
</dataResource>

Migrating applications

When migrating applications there are only two important steps:

1. Updating the settings of the project to target Jakarta.
2. Migrate custom code in harvests and ext files if needed.

Updating project settings

1. Upgrade your expansion settings (typically in conf/expansionSettings.conf) to use versions of expansion resources that support Jakarta EE.

2. In the technical infrastructure settings, the JEE version should be updated to 10:

   Java 21.xml

   <technicalInfrastructure name="Java 21">
     <javaVersion>jdk21</javaVersion>
     <jeeVersion>10</jeeVersion>
   </technicalInfrastructure>

3. Add the hibernate.version option with value 6 to your Application model.

   myapplication.xml

   <application name="myapplication">
     <shortName>myapplication</shortName>
     <version>1.0.0</version>
     <components>
       <component name="account"/>
       <component name="assets"/>
       <component name="utils"/>
       <component name="validation"/>
       <component name="workflow"/>
       <component name="applicationStuff"/>
     </components>
     <options>
       <hibernate.version>6</hibernate.version>
     </options>
   </application>

4. Update the TomEE base image for Docker to a TomEE 10 variant. The latest version can be found on the documentation page for the base image. Today, this is:

   • docker.normalizedsystems.org/nsx-tomee-base:10.1.2-3.11.1 for root-based images
   • docker.normalizedsystems.org/nsx-tomee-base:10.1.2-3.11.1-rootless for rootless images

Migrating custom code

Most custom code will be compatible with Jakarta EE already and will not require any changes. The majority of required changes will be the package names that changed from javax.* to jakarta.*. These are easy to identify once you migrate the project settings and expand, as those imports will no longer be found. This is solved by simply replacing import javax. with import jakarta..

Warning

Be careful when replacing imports. While the majority of imports in javax packages have moved to jakarta packages, this is not true for all imports!

The switch to Jakarta occurred when Oracle transferred Java EE to Eclipse Foundation. Because Oracle owns the Java trademark, the name had to change under Eclipse Foundation to Jakarta to avoid trademark conflicts. There are also classes in javax packages that are part of the standard Java platform API, which is still owned by Oracle and such they were not renamed to jakarta.

An example of classes that were not renamed is everything in javax.naming.