DEV Community

Cover image for 🚀 Upgrading Your Legacy Java 8 + Spring Boot 2.1 Project to Java 17 (Without Breaking Everything)
araf
araf

Posted on

🚀 Upgrading Your Legacy Java 8 + Spring Boot 2.1 Project to Java 17 (Without Breaking Everything)

#programming #java #beginners #tutorial

Upgrading a large Java 8 + Spring Boot 2.1 codebase to Java 17 feels scary.
Modules, removed APIs, dependency conflicts, Jakarta migration — a lot can break.

This guide gives you a safe, production-tested path to upgrade without downtime.

✅ Why Upgrade to Java 17?

Benefit Why It Matters
LTS until 2029 Long-term support & security updates
40–60% faster JVM Better GC (G1/ZGC), faster execution
Modern language features var, records, sealed classes, switch expressions
Better memory usage Reduced heap footprint
More secure Stronger TLS, crypto, JVM rules

🧭 Safe Upgrade Path (The Only Path That Won’t Break Everything)

  • Phase 1 → Java 8 → Java 11
  • Phase 2 → Spring Boot 2.1 → 2.7
  • Phase 3 → Java 11 → Java 17
  • Phase 4 → Spring Boot 2.7 → 3.x (Jakarta)

🔹 Phase 1 — Upgrade Java 8 → Java 11

Update pom.xml:

<properties>
    <java.version>11</java.version>
</properties>
Enter fullscreen mode Exit fullscreen mode

Fix removed Java EE modules:

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>
Enter fullscreen mode Exit fullscreen mode

Check incompatible libraries:

mvn dependency:tree
Enter fullscreen mode Exit fullscreen mode

🔹 Phase 2 — Upgrade Spring Boot 2.1 → 2.7

Update Boot version:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version>
</parent>
Enter fullscreen mode Exit fullscreen mode

Things to fix before Spring Boot 3:

  • Replace Springfox with springdoc-openapi
  • Move to new constructor-binding style for @ConfigurationProperties
  • Clean deprecated security config
  • Start migrating from RestTemplate → WebClient (optional)

🔹 Phase 3 — Upgrade Java 11 → Java 17

Update in pom.xml:

<properties>
    <java.version>17</java.version>
</properties>
Enter fullscreen mode Exit fullscreen mode

Common fixes:

  • Reflection warnings (--add-opens)
  • Replace any legacy HTTP clients
  • Ensure all dependencies support Java 17

🔹 Phase 4 — Upgrade Spring Boot 2.7 → 3.x (Jakarta Mandatory)

Spring Boot 3 uses Jakarta EE 9+.
All javax.* packages are now jakarta.*.

Example:

import javax.servlet.http.HttpServletRequest;
Enter fullscreen mode Exit fullscreen mode

becomes:

import jakarta.servlet.http.HttpServletRequest;
Enter fullscreen mode Exit fullscreen mode

Update Boot:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.4</version>
</parent>
Enter fullscreen mode Exit fullscreen mode

Required Migrations

1. Javax → Jakarta

Run to find:

grep -R "javax" src/
Enter fullscreen mode Exit fullscreen mode

2. Spring Security Rewrite

Old:

http.authorizeRequests().anyRequest().authenticated();
Enter fullscreen mode Exit fullscreen mode

New:

http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/api/**").authenticated()
);
Enter fullscreen mode Exit fullscreen mode

3. Hibernate/JPA

Replace:

<groupId>javax.persistence</groupId>
Enter fullscreen mode Exit fullscreen mode

with:

<groupId>jakarta.persistence</groupId>
Enter fullscreen mode Exit fullscreen mode

4. Swagger Migration

Remove Springfox and add:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.6.0</version>
</dependency>
Enter fullscreen mode Exit fullscreen mode

🧪 Testing Strategy

Add JDK 17 to CI 

- name: Setup JDK
  uses: actions/setup-java@v3
  with:
    distribution: 'temurin'
    java-version: '17'
Enter fullscreen mode Exit fullscreen mode

Run full integration tests

  • Controllers
  • WebClient/Feign
  • Kafka/RabbitMQ
  • Flyway/Liquibase
  • Full database workflows

🧰 Common Issues & Fixes

Error Fix
ClassNotFound: javax.* Replace with jakarta
Spring Security not working Rewrite security config
Swagger UI not loading Use springdoc-openapi, not Springfox
Reflection warnings Temporary: --add-opens

🏁 Final Upgrade Checklist

Java Upgrade

  • [ ] Java 8 → 11
  • [ ] Fix removed Java EE modules
  • [ ] Java 11 → 17
  • [ ] Update CI pipeline

Spring Boot Upgrade

  • [ ] Upgrade 2.1 → 2.7
  • [ ] Remove deprecated Spring APIs
  • [ ] Upgrade 2.7 → 3.x
  • [ ] Migrate javax → jakarta
  • [ ] Update Spring Security
  • [ ] Replace Springfox → springdoc
  • [ ] Update Hibernate/JPA
  • [ ] Run full integration tests

🎉 Conclusion

Upgrading Java 8 + Spring Boot 2.1 directly to Java 17 + Spring Boot 3.x is risky.
But using the safe 4-phase approach prevents almost all breaking changes:

1️⃣ Java 8 → 11
2️⃣ Spring Boot 2.1 → 2.7
3️⃣ Java 11 → 17
4️⃣ Spring Boot 2.7 → 3.x (Jakarta)

Follow the checklist, fix deprecated APIs early, and test thoroughly — and your upgrade will be smooth.

Top comments (0)