Migrate from javax.* (Java EE) to jakarta.* (Jakarta EE 9+) to enable Spring 6 / modern stack

[ismisepaul]

Summary

Migrate the entire codebase from the legacy Java EE javax.* namespace to Jakarta EE 9+ jakarta.*, and raise the runtime/build baseline accordingly. This is a prerequisite for upgrading Spring Framework to 6.x (and keeping all the transitive deps that have moved to Jakarta).

Motivation

Dependabot PR #770 (bump spring-test 5.3 → 6.0.12) cannot be merged. Spring Framework 6.0 hard-requires Jakarta EE 9+ and Java 17+; its MockHttpServletRequest / MockServletConfig now implement jakarta.servlet.* interfaces, so they no longer satisfy our javax.servlet.* code and compilation fails with ~50 errors across the IT/test sources, e.g.:

incompatible types: org.springframework.mock.web.MockServletConfig
  cannot be converted to javax.servlet.ServletConfig
incompatible types: org.springframework.mock.web.MockHttpServletRequest
  cannot be converted to javax.servlet.http.HttpServletRequest

We are currently pinned to Spring 5.3.31, which is past end of OSS support. There is no path to a modern Spring/servlet stack without the Jakarta migration — it's the only option.

Scope

Current state in the repo:

• 168 Java files import javax.servlet (814 import statements total).
• Other javax.* in play: javax.xml (6), javax.crypto (5, stays javax — JCA is not part of Jakarta), javax.mail (2, → jakarta.mail).
• 122 JSP files + src/main/webapp/WEB-INF/web.xml (taglib URIs and servlet descriptor move to Jakarta namespaces).
• Packaging is war, deployed on Tomcat (Dockerfile FROM tomcat:${TOMCAT_DOCKER_VERSION}).
• Compiler <release> is already 17 — good, satisfies the Spring 6 / Jakarta baseline.

Work items

• Swap servlet dependency: javax.servlet:javax.servlet-api:4.0.1 → jakarta.servlet:jakarta.servlet-api (6.x, Servlet 6.0).
• Replace jstl:jstl:1.2 with the Jakarta JSTL API + Glassfish impl (jakarta.servlet.jsp.jstl:*).
• javax.mail → jakarta.mail (com.sun.mail:jakarta.mail / org.eclipse.angus).
• Review javax.xml usages (JAXB/javax.xml.bind → jakarta.xml.bind if any; javax.xml.parsers/SAX stay in the JDK).
• Bump Spring spring-web / spring-core / spring-context / spring-test to 6.x (then let Dependabot Bump org.springframework:spring-test from 5.3.23 to 6.0.12 #770 ride along / close it).
• Update the spring-mock / fongo test mocks if they conflict with Jakarta.
• Bulk rename import javax.servlet* → import jakarta.servlet* across the 168 source files (OpenRewrite recipe org.openrewrite.java.migrate.jakarta.JavaxServletToJakartaServlet is the recommended tool for this).
• Reimplement SAML SSO on a Jakarta-native library (decision: pac4j pac4j-saml 6.x) and rewrite the 5 SAML servlets (ACS, SLS, SSOLogin, Logout, SSOMetadata) — building a SAML2Configuration from onelogin.saml.properties, preserving the Getter.authUserSSO(...) hand-off. In-scope migration blocker, done as its own stacked PR. Earlier plan (java-saml 3.0.0 + java-saml-servlet-jakarta) is dead: verified — java-saml's latest release is 2.9.0 (javax-only Auth); the servletless/jakarta split (PR Add Axway to Sponsors #395) is stalled; java-saml-core 3.x was never published; the only jakarta artifact (Jumpmind 3.0.0.231010) is a 4 KB, 2-class adapter stub with no Auth/core — unusable.
• Migrate 122 JSPs: update taglib URIs (http://java.sun.com/jsp/jstl/... → jakarta.tags.*) and any scriptlet imports.
• Update web.xml to the Jakarta web-app schema/namespace (Servlet 6.0, jakarta.ee).
• Bump the Tomcat base image to Tomcat 10.1+ (first Jakarta-namespace Tomcat); Tomcat 9 will not run a Jakarta servlet app.
• Run the full unit + integration test suite green.

Notes

• javax.crypto stays as-is — it's part of the JCA in the JDK, not Jakarta EE.
• Recommend driving the namespace + import changes with OpenRewrite (org.openrewrite.recipe:rewrite-migrate-java, recipe org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta) to handle the mechanical bulk and reduce review surface, then hand-fix the JSP/web.xml/Tomcat pieces.

Refs: PR #770 (build failure that surfaced this).

[ismisepaul]

Implementation plan (for review before PRs land)

Posting the approach up front so the mechanical bulk can be trusted by construction and reviewers focus where judgement is needed. Numbers are from a fresh audit of dev (as of the 2026-06-04 Dependabot merges).

Why Jakarta / alternatives considered

javax.* is a frozen namespace — when Java EE moved to the Eclipse Foundation (Jakarta EE), Oracle retained the javax trademark, so no spec evolves there anymore. Spring 6 / Tomcat 10+ / modern servlet containers are all Jakarta-only. Staying on javax means staying on Spring 5.3 (past OSS end-of-support) and Tomcat 9 (winding down), permanently unable to take security patches — and is exactly why Dependabot #770 can't merge. Alternatives (do nothing / pin Spring back / full re-platform) all either leave us unsupported or end up at Jakarta anyway at higher cost. Migration is the only path that keeps the app on a supported, evolving stack.

Current-state audit

Item	State	Action
javax.servlet	170 files / 818 import lines, 0 usages in code bodies (all import lines)	bulk rename
javax.xml	only javax.xml.parsers.*	stays (JDK)
javax.crypto	2 files	stays (JCA, not Jakarta)
javax.mail	1 file, dep com.sun.mail:javax.mail:1.6.2	→ org.eclipse.angus:angus-mail
JSP taglibs	only jstl/core + jstl/fmt (2 distinct URIs across 122 JSPs)	→ jakarta.tags.*
web.xml	javaee ns, version 2.5	→ Jakarta web-app_6_0, version 6.0
Tomcat	9.0-jre17-temurin (.env)	→ 10.1-jre17-temurin (first Jakarta Tomcat)
<release>	already 17	already meets baseline
Spring	inconsistent on dev: web 6.1.21, core 6.0.2, test + context still 5.3.31	align all to 6.1.x (see note)
spring-mock:2.0.8	javax-era standalone mock (2008)	delete — spring-test 6 provides Jakarta MockHttpServletRequest/MockServletConfig
fongo:2.1.1	unused — its only 2 tests are @Disabled (NPE vs mongo-driver 3.12.14)	drop dep; tests rescued separately in #876
javax:javaee-api:8.0.1 (provided)	legacy umbrella, pulls javax back in	remove

Spring version target: 6.1.x (not 7)

Dependabot #869 proposes spring-core 7.0.7. We are deliberately targeting Spring 6.1.x for this migration: it's the minimum that satisfies #861, matches spring-web 6.1.21 already merged on dev, and stays on Jakarta EE 9 / Servlet 6.0 / Tomcat 10.1. Spring 7 (Jakarta EE 11 / Servlet 6.1 / Tomcat 11) is a deliberate follow-up, not part of this PR — jumping mid-migration widens the blast radius. Recommend holding/closing #869 until this lands.

Branching

Long-lived integration branch feat/jakarta-migration off dev. Each sub-PR targets the feat branch and is reviewed/merged individually; the feat branch need not compile mid-stack. A single final atomic PR feat/jakarta-migration → dev lands the green result. Note: Dependabot is actively churning dev (10 merges on 2026-06-04), so the feat branch will be rebased on dev frequently to avoid drift.

Sub-PRs

1. Build config only — pom Jakarta dependency swaps (servlet-api 6.0, jakarta JSTL api+impl, angus-mail), drop javaee-api/spring-mock/fongo, align Spring to 6.1.x; .env Tomcat → 10.1. Self-contained; won't compile alone (expected).
2. OpenRewrite mechanical rename — org.openrewrite.recipe:rewrite-migrate-java, recipe JavaxMigrationToJakarta. 100% machine-generated, no hand edits; diff is purely javax.* → jakarta.* imports. One PR with 5 package-scoped commits (servlets/module/challenge, servlets/admin/*, rest of servlets/module+api, other src/main, src/it+src/test) so reviewers can go commit-by-commit or trust tool+CI.
3. JSP / web.xml / Tomcat — the human-read part: 2 taglib URIs, web.xml schema bump, Tomcat 10.1, confirm webxml.patch/serverxml.patch still apply.
4. Spring 6.1 finalisation + tests green — resolve any spring-test 6 mock fallout, full mvn verify, docker compose up JSP-rendering smoke test. Update the two MongoDatabaseIT @Disabled reasons to point at Modernize MongoDatabase off legacy com.mongodb.DB API + Testcontainers; rescue disabled MongoDatabaseIT tests #876.

What intentionally does NOT change

javax.crypto.* and javax.xml.parsers.* stay — JDK/JCA, not Jakarta EE. An untouched javax.crypto import in the diff is correct, not a miss.

Closes #770 once landed. Test rescue tracked in #876.

[ismisepaul]

Progress checkpoint — pause here, resume after #877 + #878 merge

Status of the stacked migration so far, including a newly-discovered blocker that needs resolving before #878 can go green.

Branches / PRs

• Integration branch: feat/jakarta-migration (off dev).
• build: jakarta-ready dependencies (PR 1 of jakarta migration #861) #877 — PR 1 (branch pr1-jakarta-build-config), build config only (pom.xml + .env): Jakarta deps, Spring aligned to 6.1.21, spring-mock/fongo/javaee-api removed, Tomcat 10.1. Base: feat/jakarta-migration.
• refactor: mechanical javax->jakarta import rename (PR 2 of jakarta migration #861) #878 — PR 2 (branch pr2-openrewrite-jakarta-rename), mechanical javax.* → jakarta.* rename, 170 files, 5 package-scoped commits. Stacked on build: jakarta-ready dependencies (PR 1 of jakarta migration #861) #877.

What OpenRewrite did, and what was hand-corrected

Recipe org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta (rewrite-migrate-java:RELEASE). Reproduction gotcha: the recipe must compile the source to rewrite it, so it needs the javax deps present — but PR 1 already removed them. To re-run: temporarily add the old javax deps (javax.servlet-api, jstl, com.sun.mail:javax.mail) back alongside the jakarta ones so the source parses, run the recipe, then git checkout pom.xml to restore PR 1's clean pom — keeping only the source import changes. The import rename itself is clean, but the recipe bundled two non-mechanical changes that were reverted to keep #878 a pure rename:

1. Behavioral: ses.invalidate() → request.logout() in Login, Logout, MobileLogin, SLS, ACS. Not equivalent — request.logout() does not clear session attributes; LogoutIT asserts userStamp == null after logout and would have failed. Reverted.
2. web.xml / tomcatShepherdSampleWeb.xml namespace edits → deferred to PR 3. (For reference, OpenRewrite emitted web-app_5_0; we want web-app_6_0 for Servlet 6.0 / Tomcat 10.1.)

Intentionally unchanged: javax.crypto.* (2 files) and javax.xml.parsers.* (4 files) — JDK/JCA, not Jakarta.

🚧 BLOCKER (new, not in original scope): com.onelogin:java-saml:2.9.0 is javax-only

CI dispatch on #878 is red — and correctly so. The SAML library's Auth(HttpServletRequest, HttpServletResponse) constructor expects javax.servlet.*. Once our SAML servlets use jakarta.servlet.*, they no longer compile:

ACS.java / Logout.java / SLS.java / SSOLogin.java:
  no suitable constructor found for Auth(jakarta.servlet.http.HttpServletRequest, ...)

Resolution (UPDATED — earlier java-saml 3.0.0 plan was wrong): verified there is no usable Jakarta release of java-saml — latest is 2.9.0 (javax-only Auth); java-saml-core 3.x was never published; the only jakarta artifact (Jumpmind 3.0.0.231010) is a 4 KB 2-class stub. Decision: reimplement SSO on pac4j pac4j-saml 6.x (maintained, Jakarta-native, complete SAML SP). It's a localized rewrite of the 5 SAML servlets (ACS, SLS, SSOLogin, Logout, SSOMetadata) — build a SAML2Configuration from onelogin.saml.properties, keep the Getter.authUserSSO(...) hand-off. In-scope #861 blocker, done as its own stacked PR.

CI dispatch results (via workflow_dispatch)

• build: jakarta-ready dependencies (PR 1 of jakarta migration #861) #877: red — expected (PR 1 doesn't compile alone).
• refactor: mechanical javax->jakarta import rename (PR 2 of jakarta migration #861) #878: red — due to the java-saml blocker above (not the rename itself).

Test coverage

Untested SAML auth servlets (SLS, ACS) are tracked separately in #879.

Where to pick up

1. Merge build: jakarta-ready dependencies (PR 1 of jakarta migration #861) #877, then refactor: mechanical javax->jakarta import rename (PR 2 of jakarta migration #861) #878, into feat/jakarta-migration (their red CI is expected partial-step red; merging a sub-PR into feat does not run CI).
2. Open the java-saml PR into feat (the in-scope blocker above) — until mvn clean test-compile is green.
3. Open the draft umbrella PR feat/jakarta-migration → dev (drafts DO trigger CI here — no draft gating — and draft blocks accidental merge); this is the real green gate.
4. PR: JSP taglibs (jakarta.tags.*), web.xml → web-app_6_0, Tomcat 10.1 patches.
5. PR: Spring 6.1 finalisation, full mvn verify + docker compose JSP smoke test; update the MongoDatabaseIT @Disabled reasons to point at Modernize MongoDatabase off legacy com.mongodb.DB API + Testcontainers; rescue disabled MongoDatabaseIT tests #876.

Related: #876 (Mongo test rescue), #869 (Spring 7 held until this lands), #770 (closed by this).