Java EE 8 to Jakarta EE 10 Migration Plan for Real Apps
Move a Java EE 8 application to Jakarta EE 10: pick a server, rename javax to jakarta, update libraries, fix descriptors, test and roll out.

Java EE 8 was the last release under the javax namespace. Jakarta EE 9 renamed it to jakarta, and Jakarta EE 10 modernized the APIs. Everything that interacts with the platform has to change together, which makes this a project, not an edit. The background is in the namespace change and the release notes in what Jakarta EE 10 adds.
Step 1: inventory
Before changing anything, list what you depend on:
grep -rl "javax\.\(servlet\|persistence\|ws.rs\|inject\|validation\|enterprise\|faces\|annotation\|transaction\|jms\|mail\|json\|websocket\|security\)" src | wc -l
mvn dependency:tree | grep -E "javax\.|hibernate|jersey|resteasy|jackson|primefaces|omnifaces"Every library found in the tree needs a Jakarta-compatible release, or a replacement. Typical examples are Hibernate (5.x to 6.x), Jersey (2.x to 3.x), RESTEasy, Jackson's JAX-RS provider modules, PrimeFaces, OmniFaces and the JDBC pool.
Step 2: pick the target
| Target | Notes |
|---|---|
| WildFly 27 or later, Payara 6, Open Liberty | Full or Web Profile servers certified for Jakarta EE 10 |
| Tomcat 10.1 | Servlet 6.0 and related web APIs only |
| Jetty 12 | Servlet 6.0 |
| Quarkus or Spring Boot 3 and later | Use Jakarta APIs without a classic server |
Choose the profile your application needs. The distinctions are explained in Jakarta EE profiles. Java 11 is the minimum for Jakarta EE 10, and Java 17 or 21 is the sensible runtime.
Step 3: rename
Run an automated recipe on a branch:
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
-Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakartaThe recipe rewrites imports, pom.xml coordinates and many descriptors. The steps are in OpenRewrite for javax to jakarta, and the manual route is in migrating by hand. What a tool misses:
- XML descriptors.
web.xml,persistence.xml,beans.xmlandfaces-config.xmluse namespaces and version numbers. Update them to the Jakarta schemas (https://jakarta.ee/xml/ns/jakartaee). - Strings that name classes. Reflection,
Class.forName("javax.ws.rs...")and property keys such asjavax.persistence.jdbc.urlchange tojakarta.persistence.jdbc.url. - Generated code. Regenerate JAXB, JPA metamodel and OpenAPI clients with Jakarta plugins.
Step 4: dependencies
Move dependencies to Jakarta releases, and remove duplicate APIs that servers already provide:
<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-api</artifactId>
<version>10.0.0</version>
<scope>provided</scope>
</dependency>Then fix the errors that appear when a library still brings javax classes, diagnosed in javax and jakarta ClassNotFoundException.
Step 5: removed and changed behaviour
Jakarta EE 10 removed some old pieces: parts of the Managed Beans specification and a number of deprecated APIs, and CDI bean discovery defaults. Verify:
- Bean discovery mode, because CDI Lite changes defaults for archives without
beans.xml. - Removed
@ManagedBeanand oldjavax.faces.beanannotations, replaced by CDI. See managed beans versus CDI. - Security configuration, which differs between servers.
Step 6: test and roll out
- Run unit tests, then integration tests on the target server in a container.
- Run the application against a copy of production data.
- Deploy to a staging environment and compare behaviour and logs.
- Roll out behind a switch, or per environment, with a way back.
Keep every step in its own commit.
A risk register that goes in the plan
A migration stalls on the items nobody listed. Write them down at the start, with an owner:
| Risk | How to find it | Mitigation |
|---|---|---|
| A library with no Jakarta release | jdeps on every jar, or search for javax/ entries | Replace it, fork it, or transform the jar |
| Application server not available for the target version | Check the vendor's support matrix | Choose another runtime or wait |
| Removed Faces managed beans | Search for javax.faces.bean | Convert to CDI, see the bean comparison |
| JAXB, JAX-WS or JavaBeans Activation relied on from the JDK | Compile errors on Java 11 and later | Add jakarta.xml.bind and its runtime as dependencies |
| Behaviour change in CDI discovery | Beans missing after the move | Check beans.xml and the discovery mode |
| Generated code | Generators emit the old imports | Upgrade the plugins |
| Tests that depend on the old server | Arquillian or embedded container setups | Update the test runtime in step |
Review the register after each step, since the answer to some entries only appears once the code compiles.
Count the work first
A few commands size the job. They count source files that import the old packages and the descriptors that carry the old namespace:
grep -rl 'import javax\.\(servlet\|persistence\|ejb\|faces\|ws\|validation\|inject\|enterprise\|annotation\)' src | wc -l
grep -rl 'xmlns="http://xmlns.jcp.org\|java.sun.com/xml/ns/javaee' src | wc -lA project with 300 files and 5 descriptors is a day of mechanical changes with a tool, and a week of testing. A project with 3,000 files and a dozen custom extensions takes longer, and the dominant cost is testing, not editing. The count gives a conversation about time that is based on facts.
Behaviour that changed with the move to 10
Beyond the rename, Jakarta EE 10 removed deprecated APIs and changed defaults:
| Area | Change |
|---|---|
| Faces 4.0 | The old managed bean annotations are removed, and CDI is the only bean model |
| CDI 4.0 | A bean archive without beans.xml is treated as annotated discovery, only classes with a bean-defining annotation count |
| Servlet 6.0 | Several deprecated methods were removed, and HttpServletRequest methods changed in places |
| Persistence 3.1 | UUID is a supported basic type, and some query functions were added |
| Security | A new authentication mechanism API, and the older Java EE security classes are gone |
| Concurrency | Virtual thread support arrived with the later 3.1 release |
Read the change log for each specification you use. The ones that are used by an application, not the whole list, determine the work.
Run old and new in parallel
A big-bang switch has no rollback. Deploy the migrated build next to the old one, send a small share of traffic to it, and compare errors and latency before the share grows. Keep database changes compatible with both versions during the overlap, since both write to the same schema. If a change cannot be compatible, split it into two releases, one before the move and one after.
Decide what you are not doing
State the scope in writing: the Java version, the platform version and the application server. Dependencies not needed for the move stay at their versions, since upgrading everything at once makes failures impossible to place. Frameworks that changed their own major version, such as Hibernate and Spring, come with the namespace change, so plan them as part of it, and keep unrelated upgrades for after.
Where this does not apply
If you are on Java EE 7 or older, upgrade to 8 first. If the end goal is Spring Boot, the order is different, with the namespace changing as part of the Spring Boot 3 upgrade. The reference is the Jakarta EE 10 platform page, and Jakarta EE lists compatible products.


