Most guides make the Java EE to Jakarta EE migration sound like a find-and-replace job: change javax to jakarta, rebuild, done. I am leading this migration on a large enterprise application that processes payments every day, and the rename turned out to be the easy part. The hard parts were configuration files nobody remembered, an application server upgrade, and a persistence layer that suddenly disagreed with queries that had worked for years.
This is the checklist I wish I had at the start. It assumes a typical stack: EJB, JPA with Hibernate, Servlets and REST, running on WildFly, moving to Java 21.
For context, the application is a pension administration platform. It covers member records, contributions, benefit calculations, claims, and fees and commissions, and it handles financial processing for pension funds every day. That last point shaped every decision: the system could not be taken offline for a "big bang" rewrite, and a wrong number in a report is far worse than a failed deployment.
Why the migration is not optional anymore
When Java EE moved to the Eclipse Foundation, Oracle kept the javax trademark. From Jakarta EE 9 onward, every specification API moved to the jakarta.* namespace. Modern application servers, current Hibernate releases and recent Spring versions all target jakarta.*. Staying on javax.* means staying on old, unsupported versions of everything else.
Step 1: Inventory before you change anything
Before touching code, list what you actually depend on:
- Every
javax.*import, grouped by package. A quick count tells you where the work is:
grep -rhoE "import javax\.[a-z]+" src/ | sort | uniq -c | sort -rn - Third-party libraries that pull in
javaxAPIs transitively. Runmvn dependency:tree(or the Gradle equivalent) and look for anything that still depends onjavax.servlet,javax.persistenceor similar. Each one needs a Jakarta-compatible version. - XML descriptors:
persistence.xml,web.xml,beans.xml,ejb-jar.xml, plus any server-specific deployment files. - Reports, scripts and generated code that reference classes by fully qualified name. Report templates are easy to forget.
Step 2: Know which javax packages do NOT change
This catches people out. Only the Java EE specification packages moved. Packages that belong to the JDK itself stay as they are, for example:
-
javax.sql(DataSource) -
javax.naming(JNDI) -
javax.cryptoandjavax.net.ssl -
javax.transaction.xa(the XA interfaces in the JDK), even thoughjavax.transaction(JTA) becomesjakarta.transaction
A blind global replace of javax. with jakarta. will break these. Replace package by package instead.
Step 3: Let a tool do the bulk rename
Do not do the namespace change by hand. Use one of:
- OpenRewrite, which has a recipe for exactly this migration and also updates dependencies.
- IntelliJ IDEA's built-in "Migrate Packages and Classes" refactoring for Java EE to Jakarta EE.
- Eclipse Transformer, if you need to transform binary artifacts you cannot rebuild.
Run the tool on a clean branch, commit the result on its own, and keep it separate from manual fixes. Reviewers can then skim the mechanical commit and focus on the real changes.
Step 4: Update the XML descriptors
Imports are only half of it. The descriptors have new namespaces too. For JPA, a persistence.xml header looks like this:
<persistence xmlns="https://jakarta.ee/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd" version="3.0"> Also check property names. Standard properties that started with javax.persistence. now start with jakarta.persistence., for example:
<property name="jakarta.persistence.jdbc.url" value="..."/> Do the same for web.xml and beans.xml. An old namespace in a descriptor often fails quietly: the file is ignored rather than rejected, so a feature simply stops working.
A useful habit: after each deployment, check the server log for the persistence unit and CDI startup messages, not just for errors. If your persistence unit or your CDI beans are not being picked up at all, an old namespace or property name in a descriptor is one of the first things to check.
Step 5: Upgrade the application server deliberately
Recent WildFly releases support only Jakarta EE, so the server upgrade and the namespace change usually happen together. Things to plan for:
- Read the release notes for every major version you skip, not just the target one.
- Security configuration: if you are coming from a much older WildFly, the legacy security subsystem has been replaced by Elytron. Security domains need to be redefined.
- Datasources and JNDI names: confirm they still resolve. Write a tiny smoke test that looks up each datasource after deployment.
- Java 21: check for libraries that use removed or restricted JDK internals. Add the
--add-opensflags you need explicitly and document why, rather than copying a long list from the internet.
Step 6: Treat the Hibernate upgrade as its own project
This is where most of my time went. Moving from Hibernate 5 to 6 and then 7 is a bigger change than the namespace rename. Hibernate 6 introduced a new query parser that is much stricter about HQL and JPQL, and Hibernate 7 implements Jakarta Persistence 3.2 and removes APIs that were deprecated in 6.
What to look out for:
- Queries that "worked" because the old parser was forgiving. Implicit joins, ambiguous paths and type mismatches in comparisons can now fail at startup or at runtime.
- Native queries returning different Java types. Scalar results now follow the JDBC type more closely. Code that cast a result to a specific numeric type can throw a
ClassCastException. Read numbers throughNumberand convert explicitly. - Removed legacy APIs. The old
org.hibernate.CriteriaAPI is gone, andSessionmethods such assave,updateandsaveOrUpdatewere deprecated in favour ofpersist,mergeandremove. Find them early with a search. -
ResultTransformerusage, which was replaced by newer transformer interfaces. - ID generator and sequence naming defaults, which changed in Hibernate 6. If you rely on implicit sequence names, set them explicitly so new rows do not collide with existing IDs.
Always check the official Hibernate migration guide for each version you pass through. It lists every behavioural change, and it is far more reliable than blog posts, including this one.
Here is a typical pattern to watch for. Older code often reads a count or a sum from a native query and casts it straight to a specific type:
// Before: assumes the driver returns BigDecimal BigDecimal total = (BigDecimal) em.createNativeQuery( "SELECT SUM(amount) FROM contribution WHERE member_id = :id") .setParameter("id", memberId) .getSingleResult(); If the result type changes after an upgrade, this compiles fine and then fails at runtime with a ClassCastException, often in a code path that only runs at month end. A safer version reads the value as a Number and converts it explicitly:
// After: works whatever numeric type the driver returns Number result = (Number) em.createNativeQuery( "SELECT SUM(amount) FROM contribution WHERE member_id = :id") .setParameter("id", memberId) .getSingleResult(); BigDecimal total = result == null ? BigDecimal.ZERO : new BigDecimal(result.toString()); Note the null check as well: SUM returns NULL when there are no rows, which the old code would also have missed. Search your codebase for casts on getSingleResult() and getResultList() from native queries, and fix them all in one pass.
Step 7: Pin down behaviour with tests before you fix queries
The biggest risk in a live financial system is not a query that fails loudly. It is a query that runs fine but returns slightly different results. The approach I recommend:
- Before changing a query, write a test that records what it returns today against a realistic data set.
- Migrate the query.
- Compare the results, not just whether it runs.
For reporting queries, compare totals and row counts between the old and new versions on a copy of production data. A difference of one row can mean a missing join condition.
Step 8: Roll out module by module
Do not merge the whole migration in one release if you can avoid it. Group the work by module, for example members, contributions, claims, and release behind a stable test suite each time. Keep a short log of every behaviour change you find. It becomes your team's migration guide, and the next module goes faster.
The checklist
- [ ] Inventory
javaximports, transitive dependencies and descriptors - [ ] Mark JDK
javaxpackages that must not change - [ ] Run an automated rename tool and commit it separately
- [ ] Update
persistence.xml,web.xmlandbeans.xmlnamespaces and property names - [ ] Upgrade WildFly, re-check security, datasources and JNDI
- [ ] Verify Java 21 compatibility of all libraries
- [ ] Work through each Hibernate migration guide
- [ ] Write result-comparison tests before touching queries
- [ ] Set ID generators and sequence names explicitly
- [ ] Roll out module by module, logging every behaviour change
Final thoughts
The namespace change gets the attention, but the real work in a Jakarta EE migration is in configuration, the application server and the persistence layer. If you plan for those three, and test results rather than just compilation, you can modernise a system that people depend on every day without putting it at risk.
If you are in the middle of a migration like this, I would like to hear what surprised you most.
I'm Mackrine Awino, a full-stack software engineer in Nairobi working with Java, Jakarta EE, Spring Boot and React. You can find me on LinkedIn and GitHub.