Skip to content
javahacks.dev
Jakarta EE

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.

5 min read
Summarize in AI
Flat illustration of a staircase from one version to the next, with the Spring Boot, Docker, OpenJDK, Apache Maven and Gradle logos.

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

Shell
./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.JavaxMigrationToJakarta

RELEASE 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

AreaExample
Importsjavax.persistence.Entity becomes jakarta.persistence.Entity
Fully qualified names in codejavax.servlet.http.HttpServletRequest in a field type
Dependency coordinatesjavax.servlet:javax.servlet-api becomes jakarta.servlet:jakarta.servlet-api
XML namespacesweb.xml and persistence.xml namespace URIs
Some string literalsClass 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

  1. Compile. ./mvnw -q compile shows leftover errors. A common one is a library with no Jakarta version.
  2. Search for remaining names. List candidates with the command below. Expect strings in reflection, META-INF/services files and test fixtures.
Shell
grep -rn "javax[.]" src | grep -v "javax[.]sql\|javax[.]crypto\|javax[.]net\|javax[.]naming\|javax[.]xml[.]parsers"
  1. Dependencies. ./mvnw dependency:tree | grep javax shows libraries still on the old namespace.
  2. Run the tests, including integration tests that start the server.
  3. Deploy to a Jakarta runtime. A WAR built for jakarta fails 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:

Shell
./mvnw org.openrewrite.maven:rewrite-maven-plugin:dryRun \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
  -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta

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

Shell
./mvnw org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
  -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta

Replace 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:

Shell
git diff --stat | tail -1
git diff --name-only | sed 's/.*\.//' | sort | uniq -c | sort -rn

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

Shell
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:

GapSymptom after migrationFix
A dependency built for javaxClassNotFoundException or an annotation that is ignoredUpgrade to a Jakarta release, or transform the jar
A server on the old platformDeployment fails with a missing API classMove to a Jakarta EE 9 or later runtime
Code generated at build timeGenerated sources import javaxUpgrade 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.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.