Migração javax → jakarta

Quando Usar

• O usuário solicita explicitamente a migração para o namespace jakarta, Tomcat 10+/11 ou Jakarta EE
• java-upgrade ou spring-boot-4-migration delegam a migração do namespace

Detectar apenas importações javax.* não autoriza esta migração; relate-as em vez disso.

Em projetos Spring Boot, o BOM do Boot gerencia as versões do Jakarta; não fixe as versões abaixo, e deixe a versão do Boot decidir o nível do Jakarta EE (Boot 4 = Jakarta EE 11, Servlet 6.1). Os exemplos abaixo visam Jakarta EE 10 (Servlet 6.0, Tomcat 10.1+) em projetos não-Boot.

Procedimento

Passo 0 — Linha de Base

Execute ./mvnw verify ou ./gradlew build primeiro e registre o resultado; não migre com uma linha de base vermelha. Faça a alteração em um commit/passo dedicado.

Passo 1 — Escanear Uso de javax

Procure na base de código por todas as importações javax.* que precisam de migração:

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.*

NÃO migre estas (elas permanecem em javax.*):

• javax.sql.* — parte do JDK
• javax.naming.* — parte do JDK (JNDI)
• javax.crypto.* — parte do JDK
• javax.net.* — parte do JDK
• javax.security.auth.* — parte do JDK
• javax.swing.*, javax.xml.parsers.* — pacotes JDK

Passo 2 — Atualizar pom.xml

Substitua as coordenadas das dependências. Escolha versões de API que correspondam ao runtime alvo; a tabela abaixo é para Jakarta EE 10 (Tomcat 10.1+, Servlet 6.0):

Passo 3 — Atualizar web.xml (se presente)

O version deve corresponder ao nível do Servlet alvo (5.0 para Tomcat 10.0, 6.0 para Tomcat 10.1, 6.1 para Tomcat 11); o exemplo abaixo é para 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">

Passo 4 — Atualizar Arquivos Fonte Java

Substitua apenas as importações de javax. do Jakarta EE identificadas no Passo 1 por seus equivalentes jakarta. em arquivos .java; deixe os pacotes JDK (por exemplo, javax.sql, javax.crypto) inalterados. Verifique também referências não-Java: persistence.xml (propriedades javax.persistence.*), META-INF/services, beans.xml, propriedades/YAML, nomes de classes em string e reflection.

Passo 5 — Verificar

1. Execute mvn clean compile ou gradlew build — corrija quaisquer erros de compilação
2. Execute mvn test ou gradlew test — certifique-se de que todos os testes passem
3. Procure por quaisquer importações javax.* restantes (excluindo pacotes JDK)

Fontes upstream (leia antes de migrar)

Busque a página para a versão alvo; prefira-a sobre esta skill quando houver conflitos.

• Especificações Jakarta EE: https://jakarta.ee/specifications/
• Eclipse Transformer (transformação de binário/bytecode): https://github.com/eclipse-transformer/transformer
• OpenRewrite org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta: https://docs.openrewrite.org/recipes/java/migrate/jakarta/javaxmigrationtojakarta
• Migração Tomcat 9 para 10: https://tomcat.apache.org/migration-10.html
• Guias de migração Hibernate: https://hibernate.org/orm/documentation/migrate/
• Upgrade Spring Boot 3 (linha de base Jakarta EE 9+): https://docs.spring.io/spring-boot/upgrading.html

Saída

Forneça um resumo da migração listando todos os arquivos alterados, importações substituídas e quaisquer passos manuais necessários.