javax-to-jakarta-migration

javax → jakarta Migration Skill

When to Use

• Upgrading to Tomcat 11 / Jakarta EE 10+
• Code review detects javax.* imports
• Migrating an existing project to the jakarta namespace

Procedure

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:

⚠️ Version and BOM guidance: The versions listed above were current at skill authoring time and may be outdated. Before writing these coordinates: If the project uses a BOM or <dependencyManagement> block (e.g., Spring Boot BOM, Jakarta EE BOM), do not hardcode the version — replace only the groupId and artifactId, and let the BOM manage the version. Overriding BOM-managed versions can cause runtime class mismatches. The same principle applies to Gradle projects using platform() or enforcedPlatform() dependency management.

Step 3 — Update web.xml (if present)

Locate the root <web-app> element and update the namespace URI and version attribute:

<!-- ❌ OLD — recognize this pattern and replace it; do not write this -->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="4.0">

<!-- ✅ NEW — write this instead -->
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" version="6.0">

Note on version: version="6.0" corresponds to Jakarta EE 10 (Servlet 6.0). If targeting a different Jakarta EE level, verify the correct servlet version before writing: Jakarta EE 9 / Servlet 5.0 → version="5.0" Jakarta EE 10 / Servlet 6.0 → version="6.0" Jakarta EE 11 / Servlet 6.1 → version="6.1"

Step 4 — Update Java Source Files

Replace all javax. imports with jakarta. equivalents in .java files.

Step 5 — Verify

⚠️ Developer action required — do not automate this step. After the agent completes all file rewrites, run the following commands yourself in a terminal with a trusted environment:

# Maven projects
mvn clean compile && mvn test

# Gradle projects (verify gradle/wrapper/gradle-wrapper.properties
# and the wrapper JAR checksum before executing)
./gradlew build

Do not allow the agent to execute build tools automatically. pom.xml, build.gradle, settings.gradle, and the gradlew wrapper script may contain lifecycle hooks (Maven plugins, Gradle tasks, wrapper JAR) that execute arbitrary code when the build runs.

The agent may perform the following passive verification without shell execution:

• Search for any remaining javax.* imports in .java files (excluding the JDK-retained packages listed in Step 1)
• Report any javax. strings found in pom.xml or build.gradle that were not in the migration mapping above

Output

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