Software Engineering
Migrating a legacy Java application to Spring Boot 3
By Houssem HamrouniPublished Last updated 8 min read
In short
Migrating a legacy Java application to Spring Boot 3 requires Java 17 or later, the move from javax to jakarta namespaces and an update to Spring Security 6. The safest path is incremental: upgrade to the latest Spring Boot 2.7 first, fix deprecations, then switch to 3.x with automated tools and a solid test suite.
Many enterprise applications still run on Spring Boot 2, or on older Spring and Java EE stacks. Open-source support for Spring Boot 2.7 has ended, and the ecosystem has moved on. This guide describes the migration path we apply on client projects in banking, insurance and the public sector.
What changes with Spring Boot 3
Four changes drive most of the work:
- Java 17 baseline. Spring Boot 3 and Spring Framework 6 do not run on Java 8 or 11.
- Jakarta EE 10. All
javax.*enterprise packages becomejakarta.*: persistence, servlet, validation, transactions, messaging and more. - Spring Security 6. The old
WebSecurityConfigurerAdapteris gone. Security is configured withSecurityFilterChainbeans and a lambda-based DSL, and several defaults are stricter. - Hibernate 6. JPA behaviour changes in places: ID generation, some query semantics and type mappings.
Other changes are smaller but frequent: renamed configuration properties, trailing-slash matching disabled by default in web controllers, a new observability model with Micrometer, and the removal of features deprecated during 2.x.
Step 1: take stock before touching anything
A migration fails on what nobody listed. Before changing a version number, inventory:
- Java version used to build and to run, in every environment.
- Dependencies, with versions, and whether each has a Jakarta-compatible release. Old or abandoned libraries are the main source of delay.
- Application server. If you deploy a WAR to an external server, it must support Jakarta EE 10 (for example Tomcat 10.1 or later).
- Test coverage. Identify critical flows that have no automated test.
- Integrations. SOAP clients, messaging, batch jobs, reporting engines and anything generated from WSDL or XSD.
The output is a short document: what will change, what is risky, and in which order to proceed.
Step 2: build a safety net
Test coverage is what makes a migration boring, which is the goal. If critical flows are untested, write tests first:
- Integration tests on the main REST endpoints, with a real database through Testcontainers when possible.
- Characterisation tests for complex business rules: capture today’s outputs and assert that they do not change.
- Contract tests for the interfaces you expose to, and consume from, other systems.
These tests keep their value long after the migration.
Step 3: upgrade Java first
Move the build and the runtime to Java 17 or a later long-term support release while staying on Spring Boot 2.7, which supports them. This separates two sources of problems.
Typical findings: removed JDK modules such as JAXB and JAX-WS that must become explicit dependencies, illegal reflective access in old libraries, and outdated build plugins. Fix them, release, and let the application run in production on the new Java before continuing.
Step 4: reach the latest Spring Boot 2.7
If the application is on an older 2.x or 1.x version, step up to the last 2.7 release. Then remove every deprecation warning:
- Replace
WebSecurityConfigurerAdapterwith aSecurityFilterChainbean. This is possible on 2.7 and removes the largest Spring Security change from the final step. - Add
spring-boot-properties-migratortemporarily to detect renamed configuration properties. - Replace deprecated APIs in Spring Data, Spring Batch and Actuator.
At the end of this step, the application is on Java 17 or later, on Spring Boot 2.7, with a clean build. The remaining jump is much smaller.
Step 5: switch to Spring Boot 3 and jakarta
Now change the Spring Boot version and migrate the namespaces. Automate what can be automated:
- OpenRewrite provides recipes that upgrade the build file, rename
javaximports tojakarta, and apply many Spring Boot 3 and Spring Security 6 changes in one pass. - Your IDE can also perform the
javaxtojakartarefactoring.
Then handle what tools cannot decide for you:
- Third-party libraries must be upgraded to Jakarta-compatible versions. A library that still references
javax.servletwill fail at runtime, sometimes only on a specific code path. - Not all
javaxpackages change. Packages that belong to the JDK itself, such asjavax.sqlandjavax.crypto, stay as they are. - Generated code from WSDL, XSD or OpenAPI needs updated generator plugins.
- Hibernate 6. Check ID generation strategies against your existing sequences, review native queries and custom types, and compare generated SQL on critical queries.
- Spring Security 6. Review authorisation rules.
authorizeHttpRequestsreplacesauthorizeRequests, and request matching is stricter. - URL matching.
/ordersand/orders/are no longer the same route by default. Check clients and gateways.
Step 6: test like a release, not like a patch
A framework migration touches everything, so test accordingly:
- Run the full automated suite, then a functional regression campaign on critical journeys.
- Compare performance before and after, especially database-heavy operations affected by Hibernate 6.
- Test deployments, health checks, metrics and logs in a production-like environment. Observability changes are easy to miss until the first incident.
- Verify security explicitly: authentication flows, role checks, CORS and CSRF behaviour.
Step 7: roll out progressively
For a set of microservices, migrate one low-risk service first and use it as the template. Then proceed service by service; Spring Boot 2 and 3 services can coexist as long as their contracts are stable.
For a monolith, a single switch is unavoidable, but you can reduce its risk with a canary or blue-green deployment and a tested rollback plan.
Common pitfalls
- Combining the migration with a refactoring. Do one thing at a time. A migration that also “cleans up” the architecture cannot be diagnosed when something breaks.
- Underestimating dependencies. One abandoned library can block the whole upgrade. Find these in step 1 and decide early: replace, fork or isolate.
- Long-lived migration branches. Merge small steps into the main branch continuously, or the branch will drift and the merge will become a project of its own.
- Skipping production on intermediate steps. Each stable stage in production (new Java, then 2.7 clean, then 3.x) reduces the unknowns of the next one.
After the migration
Spring Boot 3 opens options that were closed before: virtual threads on recent Java releases for I/O-heavy services, native images with GraalVM where start-up time matters, built-in observability with Micrometer, and current versions of the Spring ecosystem, including Spring AI for teams adding LLM features to Java applications.
Most of all, the application is back on a supported stack and upgrades become routine again. Keep them that way with small, regular version bumps.
Need a hand?
Harmonize IT carries out these migrations as part of our Enterprise Software Engineering service, and plans larger transformations through Architecture & Modernization. We have worked on platforms of this kind in regulated environments, such as the KYC platform for a global investment bank. To get an assessment of your application, contact us.
Frequently asked questions
Which Java version does Spring Boot 3 require?
Spring Boot 3 requires Java 17 as a minimum. We recommend moving directly to the latest long-term support release that your organisation supports to benefit from a longer support window.
How long does a Spring Boot 3 migration take?
It depends on the size of the codebase, the test coverage and the number of outdated dependencies. As a guide, a well-tested service can be migrated in days, while a large legacy application with old libraries often takes several weeks to a few months, including regression testing.
Can we migrate directly from Spring Boot 1.x or 2.0 to 3?
Technically yes, but it is risky. We recommend stepping through the latest 2.7 release first. It surfaces most breaking changes as deprecation warnings while the application still runs, which makes problems easier to isolate.
What is the javax to jakarta change?
Java EE became Jakarta EE, and from Jakarta EE 9 the package names changed from javax.* to jakarta.*. Spring Boot 3 is built on Jakarta EE 10, so imports such as javax.persistence and javax.servlet must become jakarta.persistence and jakarta.servlet, in your code and in your dependencies.
Is it worth migrating an application that works?
Yes, if the application has a future. Spring Boot 2.x no longer receives free security updates, and new versions of libraries and cloud platforms increasingly require Spring Boot 3 and a recent Java. Delaying makes the migration larger, not smaller.