What is Jakarta EE?
Jakarta EE (formerly Java EE) is a specification for Java applications and mostly used for web applications. Application servers like Apache Tomcat can be used to run applications implementing the respective APIs, e.g., the Servlet API.
Java EE was maintained by Oracle. In 2017, Oracle announced that future development will be performed by the Eclipse Foundation. The first version with the new name Jakarta EE was released in 2019, maintaining full compatibility.
Why Does This Change Produce Incompatibilities?
Because of trademark issues for the name “Java”, the existing package names used in the APIs could no longer be used. So with the release of Jakarta EE 9 in 2020, the namespace changed from “javax” to “jakarta”. For example, a class implementing a Servlet would contain an import for javax.servlet.http.HttpServlet:
import javax.servlet.http.HttpServlet;
With Jakarta EE 9 and later, this class is no longer available, so existing code must be modified:
import jakarta.servlet.http.HttpServlet;
Most application servers like Apache Tomcat can handle only one of the APIs. For example, Tomcat versions up to 9.x support Java EE while any version starting from 10.x only supports Jakarta EE.
Am I Affected by This Change?
If you host your own FirstSpirit instance or develop modules for FirstSpirit it is very likely that you are affected.
Is my FirstSpirit Instance Affected?
Your FirstSpirit installation is affected if at least one of the following conditions applies:
- Your FirstSpirit installation is not maintained in the Crownpeak Cloud and deploys web-applications to an application server like Apache Tomcat.
- You use a custom module containing a web-app component with code that uses the old Java EE API, e.g., the Servlet API.
- You use a custom module containing a web-app component with dependencies which use the old Java EE API, e..g., Spring Boot 2.x.
Is my Custom Module Affected?
Your module is affected if at least one of the following conditions applies:
- Your module contains a web-app component with code that uses the old Java EE API, e.g., the Servlet API.
- Your module contains a web-app component with dependencies which use the old Java EE API, e..g., Spring Boot 2.x.
What is the Current Status of FirstSpirit?
The current versions of FirstSpirit implement the Java EE API. As an application server, Apache Tomcat in version 9 is recommended. Modules containing web-app components must not use the Jakarta EE API at this point.
Do I Have to Prepare a New Module Version Right Now?
Probably not.
When the first version of FirstSpirit with support for Jakarta EE is released, it will contain an automatic migration tool that translates Java EE API to Jakarta EE API. Our internal tests show that most existing modules will work as before. However, there are some drawbacks:
- Deployment time will increase because of the transformation process
- If parts of the Servlet API are used that were removed with JakartaEE Servlet 6.0, the migrated code may fail at runtime (see below)
- Transforming web-app components using Spring Boot may not be possible (see below)
- Signed jars cannot be migrated because that will break the signature
If you have the chance to test your setup on a local FirstSpirit server, we highly recommend performing those tests as early as possible.
Please note: With the first release of the FirstSpirit Jakarta Edition (2023.9) we will start a transition period of 12 months during which unchanged modules will still be supported. This period must be used to migrate the module to the Jakarta EE API.
How can I Prepare for the Upcoming Changes?
We recommend testing your existing modules locally with a version of FirstSpirit supporting Jakarta EE. For this, we provide current snapshot versions of the fs-isolated-server.jar to be used in local installations as well as a Docker image shortly.
Which version of JakartaEE will be supported?
The FirstSpirit Jakarta EE Edition will support Jakarta Servlet 6.0. Please note that some deprecated parts of the Servlet API have been removed. This may cause the automatic migration to fail for some web applications.
Are There Known Libraries That Cannot be Migrated Automatically?
During our internal tests we identified some Java libraries for which the automatic migration fails. Please let us know in the comments if you find any more problematic libraries.
API Removed with Jakarta Servlet 6.0
These libraries use API that has been removed with Jakarta Servlet 6.0, so migrating the packages from javax to jakarta will not work.
What Steps are Necessary to Migrate a Module?
Since each module is unique, we can only provide rough guidelines for migrating your existing code:
- In your build tool, search for dependencies of the type javax.servlet:javax.servlet-api and replace them with jakarta.servlet:jakarta.servlet-api in Version 6.0.0.
- Additionally, search for dependencies using Java EE and replace them with newer versions, if available. For example, Spring Boot needs to be updated to 3.0.0 or later.
- Fix any compile errors occurring after performing the first two steps.
- Specify the XML schema version in the module descriptor (module-isolated.xml). FirstSpirit will evaluate this and skip the automatic migration:
<!-- Place this in module-isolated.xml, not web.xml -->
<web-app xml-schema-version="6.0">
Build and test your module thoroughly.
Please see the Jakarta Migration Guide for FirstSpirit Modules for a detailed explanation of the steps mentioned above.
What do I need to do if my WebApp-Component uses Spring Boot?
Jakarta EE is supported by Spring Boot 3.0.0 and later. If your component uses Spring Boot 2.x and is deployed as a standalone web application, the automatic migration might fail in some cases, so you need to test your application thoroughly.
However, if your component is deployed as part of the ContentCreator, you must update Spring Boot to 3.0.0 or later since versions can not be mixed in a single web application.
When Should On-Premises-Customers Switch to the Jakarta EE Edition?
In contrast to the phased rollout for cloud customers (see below), on-premises customers are able to test and migrate their FirstSpirit servers once version 2023.9 has been released. However, we strongly recommend to wait with the update of productive servers at least until release 2023.11 since we aim to guarantee the compatibility for modules provided by Crownpeak with that release.
Which Tomcat Version is Recommended for On-Premises-Customers?
If you run FirstSpirit in an on-premises-scenario, you need to upgrade your Tomcat version when switching to the Jakarta EE edition of FirstSpirit. Since the Servlet version will be updated to 6.0, you need a 10.1.x version of Tomcat.
Current Timeline
- 2023-06 Beta-version of the FirstSpirit Jakarta EE Edition is available for testing
- 2023-08 Stable release (2023.9) with support for automatic migration
- 2024-08 Support for automatic migration is removed with FirstSpirit 2024.9
Cloud Migration Schedule
To provide enough time for customers who use our SaaS offering to test the compatibility with custom modules, the Jakarta EE Edition of FirstSpirit will be rolled out in three phases. This ensures that developers can test their modules thoroughly while the prod instance remains unchanged as long as possible.
