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: ```xml <!-- 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.