javax-to-jakarta-migration

javax → jakarta Migration Skill

When to Use

• The user explicitly asks to migrate to the jakarta namespace, Tomcat 10+/11 or Jakarta EE
• java-upgrade or spring-boot-4-migration delegates the namespace migration

Detecting javax.* imports alone does not authorize this migration; report them instead.

In Spring Boot projects, the Boot BOM manages Jakarta versions: do not pin the versions below, and let the Boot version decide the Jakarta EE level (Boot 4 = Jakarta EE 11, Servlet 6.1). The examples below target Jakarta EE 10 (Servlet 6.0, Tomcat 10.1+) in non-Boot projects.

Procedure

Step 0 — Baseline

Run ./mvnw verify or ./gradlew build first and record the result; do not migrate on a red baseline. Make the change in a dedicated commit/step.

Step 1 — Scan for javax Usage

Search the codebase for all javax.* imports that need migration:

javax.servlet.*      → jakarta.servlet.*
javax.persistence.*  → jakarta.persistence.*
javax.validation.*   → jakarta.validation.*
javax.annotation.*   → jakarta.annotation.*
javax.inject.*       → jakarta.inject.*
javax.enterprise.*   → jakarta.enterprise.*
javax.faces.*        → jakarta.faces.*
javax.ws.rs.*        → jakarta.ws.rs.*
javax.el.*           → jakarta.el.*
javax.json.*         → jakarta.json.*
javax.mail.*         → jakarta.mail.*
javax.websocket.*    → jakarta.websocket.*

Do NOT migrate these (they remain in javax.*):

• javax.sql.* — part of JDK
• javax.naming.* — part of JDK (JNDI)
• javax.crypto.* — part of JDK
• javax.net.* — part of JDK
• javax.security.auth.* — part of JDK
• javax.swing.*, javax.xml.parsers.* — JDK packages

Step 2 — Update pom.xml

Replace dependency coordinates. Choose API versions that match the target runtime; the table below is for Jakarta EE 10 (Tomcat 10.1+, Servlet 6.0):

Target runtime	Jakarta EE	Servlet	Persistence	Validation	Annotations
Tomcat 10.0	9	5.0	3.0	3.0	2.0
Tomcat 10.1	10	6.0	3.1	3.0	2.1
Tomcat 11	11	6.1	3.2	3.1	3.0

Old	New
javax.servlet:javax.servlet-api	jakarta.servlet:jakarta.servlet-api:6.0.0
javax.persistence:javax.persistence-api	jakarta.persistence:jakarta.persistence-api:3.1.0
javax.validation:validation-api	jakarta.validation:jakarta.validation-api:3.0.2
javax.annotation:javax.annotation-api	jakarta.annotation:jakarta.annotation-api:2.1.1

Step 3 — Update web.xml (if present)

The version must match the target Servlet level (5.0 for Tomcat 10.0, 6.0 for Tomcat 10.1, 6.1 for Tomcat 11); the example below is for Servlet 6.0:

<!-- Old namespace -->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="4.0">

<!-- New namespace -->
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" version="6.0">

Step 4 — Update Java Source Files

Replace only the Jakarta EE javax. imports identified in Step 1 with their jakarta. equivalents in .java files; leave JDK packages (for example javax.sql, javax.crypto) unchanged. Also check non-Java references: persistence.xml (javax.persistence.* properties), META-INF/services, beans.xml, properties/YAML, string class names and reflection.

Step 5 — Verify

1. Run mvn clean compile or gradlew build — fix any compilation errors
2. Run mvn test or gradlew test — ensure all tests pass
3. Search for any remaining javax.* imports (excluding JDK packages)

Upstream sources (read before migrating)

Fetch the page for the target version; prefer it over this skill when they conflict.

• Jakarta EE specifications: https://jakarta.ee/specifications/
• Eclipse Transformer (binary/bytecode transformation): https://github.com/eclipse-transformer/transformer
• OpenRewrite org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta: https://docs.openrewrite.org/recipes/java/migrate/jakarta/javaxmigrationtojakarta
• Tomcat 9 to 10 migration: https://tomcat.apache.org/migration-10.html
• Hibernate migration guides: https://hibernate.org/orm/documentation/migrate/
• Spring Boot 3 upgrade (Jakarta EE 9+ baseline): https://docs.spring.io/spring-boot/upgrading.html

Output

Provide a migration summary listing all files changed, imports replaced, and any manual steps required.