Migrate javax to jakarta With OpenRewrite Step by Step
Run the OpenRewrite javax to jakarta recipe on a Maven or Gradle project, review the diff, fix the leftovers and verify the result with tests.

Renaming javax to jakarta across a codebase is a mechanical job that a tool does well and a text editor does dangerously. OpenRewrite parses your code and applies a recipe, so it renames what it should and leaves the JDK's own javax packages alone. This post runs it on a Maven project. The reason for the rename is in the namespace change post.
Prepare
Start from a clean working tree on a new branch, with the tests passing. The migration should produce one commit you can read as a whole. If the project is on Spring Boot 2, decide whether you are migrating to Spring Boot 3 at the same time. The Spring Boot recipes cover more than the namespace, and the Jakarta recipe alone does not update Spring itself.
Run the recipe on Maven
./mvnw -U org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
-Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakartaRELEASE fetches the current version of the recipe library; pin a version in the POM for repeatable runs. The command rewrites the files in place. Without the -U flag Maven may use a cached older version. For a dry run that only reports what would change, use the dryRun goal instead of run and read target/rewrite/rewrite.patch.
For Gradle, add the OpenRewrite plugin and declare the recipe in rewrite.yml or in the rewrite block, then run ./gradlew rewriteRun.
What it changes
| Area | Example |
|---|---|
| Imports | javax.persistence.Entity becomes jakarta.persistence.Entity |
| Fully qualified names in code | javax.servlet.http.HttpServletRequest in a field type |
| Dependency coordinates | javax.servlet:javax.servlet-api becomes jakarta.servlet:jakarta.servlet-api |
| XML namespaces | web.xml and persistence.xml namespace URIs |
| Some string literals | Class names in known configuration properties |
Review the diff with git diff --stat and then file by file for the first run. Look specifically at the pom.xml changes, because dependency versions need to match the Jakarta release line.
What to check afterwards
- Compile.
./mvnw -q compileshows leftover errors. A common one is a library with no Jakarta version. - Search for remaining names. List candidates with the command below. Expect strings in reflection,
META-INF/servicesfiles and test fixtures.
grep -rn "javax[.]" src | grep -v "javax[.]sql\|javax[.]crypto\|javax[.]net\|javax[.]naming\|javax[.]xml[.]parsers"- Dependencies.
./mvnw dependency:tree | grep javaxshows libraries still on the old namespace. - Run the tests, including integration tests that start the server.
- Deploy to a Jakarta runtime. A WAR built for
jakartafails to deploy on Tomcat 9, as in the ClassNotFoundException fix.
When the recipe is not enough
Generated code (JAXB, annotation processors, OpenAPI generators) needs its generator upgraded, not its output edited. Libraries stuck on javax need upgrading, replacing or transforming. Also expect the framework upgrade itself: moving to Spring Boot 3 changes configuration properties and removed classes, which is a separate list in the Spring migration guide. Do those as a second commit.
Run it as a dry run first
OpenRewrite can show what it would change before it writes anything, which is the safest way to see how large the job is:
./mvnw org.openrewrite.maven:rewrite-maven-plugin:dryRun \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
-Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakartaThe plugin writes a patch file under target/rewrite/rewrite.patch and prints a list of the files it would touch. Read the patch before applying. When it looks right, run the run goal in place of dryRun, then commit the result on its own so that the mechanical change is separate from any manual fix.
./mvnw org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
-Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakartaReplace RELEASE with a pinned version of the recipe artifact once you have a result you trust, so that a re-run next month produces the same output.
Review the diff by kind of change
A large diff is easier to review in groups. Count the files by extension first:
git diff --stat | tail -1
git diff --name-only | sed 's/.*\.//' | sort | uniq -c | sort -rnJava files should be nearly all import changes. XML files, such as persistence.xml, web.xml and faces-config.xml, deserve a close look, because the recipe updates namespaces and versions there and a hand-written schema location may be missed. Properties files and strings that name classes are the third group: the recipe changes some and leaves others, and a search for the old prefix finds the leftovers.
grep -rn 'javax\.' src --include='*.java' --include='*.xml' --include='*.properties' | grep -vE 'javax\.(sql|crypto|net|naming|xml\.parsers|swing|security\.auth)'An empty result, or a short list of items that you can justify one by one, is the goal.
What the recipe cannot see
A recipe works on source it parses. It does not change the jars you depend on, and it does not know what an application server provides. Three gaps recur:
| Gap | Symptom after migration | Fix |
|---|---|---|
A dependency built for javax | ClassNotFoundException or an annotation that is ignored | Upgrade to a Jakarta release, or transform the jar |
| A server on the old platform | Deployment fails with a missing API class | Move to a Jakarta EE 9 or later runtime |
| Code generated at build time | Generated sources import javax | Upgrade the generator plugin |
The last row catches projects with JAXB, JPA metamodel or OpenAPI generators. The generated classes are recreated on every build, so editing them is no use, and the plugin version is the thing to change.
Pair it with other recipes
The Jakarta recipe covers the namespace, and other recipes in the same artifact do the Java upgrade and framework changes that often arrive together. Running them one at a time, with a commit after each, makes a failure easy to place. A sensible order is the Java version first, then the namespace, then the framework upgrade, since each step assumes the one before it.
Prove it with the tests that exist
The build and the test suite are the check, and a green build after the migration says the code is consistent. It does not say that the runtime behaves the same. Deploy the result to a staging environment with the new container, and exercise the paths that use the migrated APIs: persistence, REST endpoints, validation and any servlet filters. Watch the startup log for warnings about unknown annotations, which is the signature of an unmigrated class.
Where this does not apply
For a few files, a manual change is quicker and teaches you the failure modes: see migrating by hand. OpenRewrite is a code-review aid, not a guarantee; your tests are the guarantee. The OpenRewrite documentation and the Jakarta migration recipe page describe the recipe's steps.


