How to Migrate from javax to jakarta Namespace in Java EE

Background

The shift from the javax to the jakarta namespace is one of the biggest changes in the Java ecosystem in the last two decades, affecting application servers, libraries such as Jackson, CXF, Hibernate, Spring, and even build tools. The author writes from a user perspective, aiming to discover ways to make the transition as smooth as possible.

Bytecode Enhancement Methods

The first idea is to keep the original javax packages and apply bytecode enhancement to rewrite binaries. While this can preserve source imports, it becomes complicated when reflection strings, service‑loader files, or OSGi manifests also contain the old names.

Maven Shade Plugin

The Maven Shade plugin can relocate packages. Although not designed for javax‑to‑jakarta migration, it can be used for small libraries that are not yet ready for the new namespace. The author cites TomEE’s use of the plugin to relocate the Apache ActiveMQ client (see

https://github.com/apache/tomee/blob/main/deps/activemq-client-shade/pom.xml

). The approach breaks Maven dependency management for multi‑module projects, disrupts IDE integration, and can cause mismatched Javadoc.

Eclipse Transformer

Eclipse Transformer is a generic tool built specifically for the javax‑to‑jakarta conversion. It operates on simple resources such as class files, OSGi manifests, property files, service‑loader configurations, and various text files (java source, XML, TLD, HTML, JSP). It also works on container resources like directories, JAR/WAR/EAR files, and ZIP archives. The tool can be run via an Ant task or a command‑line interface.

Deployment Phase

When using an application server, the binary can be transformed step‑by‑step before deployment. The Apache Tomcat/JakartaEE migration tool ( https://github.com/apache/tomcat-jakartaee-migration) can convert archives but only supports a subset of specifications (e.g., it does not handle JAX‑RS in TomEE). Configuration files allow selective conversion.

Runtime Phase

No viable solution was found for runtime conversion. A JavaAgent could rewrite bytecode on class load, but it adds significant startup overhead and must run on every JVM restart or class‑loader load.

Source‑Code Enhancement Methods

The author argues that source‑code changes are the safest long‑term approach, despite the effort. Early adoption is recommended because the migration represents a major API break. Tools explored include internal utilities, Eclipse Transformer, and community scripts.

IntelliJ Refactoring

IntelliJ IDEA provides a refactoring feature to rename the namespace in source code, useful for developers unfamiliar with script‑based methods.

Script Method

For simple cases, a custom script can convert sources. The SmallRye project offers an example (

https://github.com/smallrye/smallrye-config/blob/main/to-jakarta.sh

) that uses basic Linux commands to replace "javax" with "jakarta" and pushes the result to a dedicated branch, preserving separate artifact trees and avoiding Maven dependency disruption.

Generating Converted Artifacts

When publishing artifacts, developers must decide whether to maintain two branches (javax and jakarta) or use versioning to signal the namespace change. The author prefers version bumps over artifact renaming because the change is a significant API shift.

Maven Classifier

Using Maven classifiers to publish both variants is discouraged. It can cause incorrect dependency resolution, especially in multi‑module projects, and leaves Javadoc and source links pointing to the original artifact, making IDE debugging painful.

Key Takeaways

The bytecode approach was trialed in TomEE to avoid maintaining two source trees, but the risk and uncovered edge cases were too high. Out of roughly 60,000 tests (including the TCK), confidence was insufficient for production use. The method may work for small utilities, but not for real‑world applications.