This guide explains the steps necessary to convert a FirstSpirit module to be compatible with the "Jakarta Edition" of FirstSpirit.

1. Update Dependency on Servlet API

If the module brings its own classes that use the Servlet API, it is most likely that a corresponding dependency is specified in the build-tool used. In Gradle this would be

dependencies {
    compileOnly(group = "javax.servlet", name = "javax.servlet-api", version = "4.0.1")
}

The corresponding line must be adapted to reference the Jakarta Servlet API in version 6.0.0.

compileOnly(group = "jakarta.servlet", name = "jakarta.servlet-api", version = "6.0.0")

2. Rewrite Import-Statements

Now you can rewrite the import-statements in your own classes. In most cases it is sufficient to replace "javax" with "jakarta". However, in some cases further adjustments are necessary, for example if old methods have been removed with version 6.0.0. A quite common example for such a removal is HttpServletResponse#setStatus(int, String) which has been marked as deprecated since 1998.

3. Update Third-Party Dependencies

Some dependencies used in the module may use the old Servlet API and therefore need to be updated. Examples are Spring Boot or Eclipse Jersey. Please refer to the documentation of the dependencies as there were often incompatible changes during the transition to Jakarta EE.

4. Specify Servlet Version in Module Descriptor

To complete the conversion, the XML schema version should be set in the module descriptor (module-isolated.xml) for each web application:

<!-- Place this in module-isolated.xml, not web.xml -->
<web-app xml-schema-version="6.0">

This prevents automatic migration by the FirstSpirit server. If the module is created with the FirstSpirit Module Gradle plugin, this value can be set in the WebAppComponent annotation with the paramter xmlSchemaVersion. This requires at least version 4.4.0 of the plugin.

@WebAppComponent(
    name = "CustomWebApp",
    webXml = "/web.xml",
    xmlSchemaVersion = "6.0"
)