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

Source: Dev.to

Benefits

• 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

Upgrade Path

pom.xml Changes

Set Java version to 11 (Phase 1)

    11

Add missing Java EE modules (Java 11)

    javax.xml.bind
    jaxb-api
    2.3.1

Update Spring Boot version (Phase 2)

    org.springframework.boot
    spring-boot-starter-parent
    2.7.18

Set Java version to 17 (Phase 3)

    17

Upgrade to Spring Boot 3.x (Phase 4)

    org.springframework.boot
    spring-boot-starter-parent
    3.3.4

Pre‑Spring Boot 3 Adjustments

• Replace Springfox with springdoc‑openapi
• Move to the new constructor‑binding style for @ConfigurationProperties
• Clean deprecated Spring Security configuration
• (Optional) Start migrating from RestTemplate → WebClient

Add springdoc‑openapi dependency

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.6.0

Common Fixes

• Reflection warnings – add --add-opens JVM arguments temporarily
• Replace any legacy HTTP clients with modern alternatives (e.g., WebClient)
• Ensure all third‑party libraries support Java 17

Package Migration Example (Jakarta)

// Before (Spring Boot 2.x)
import javax.servlet.http.HttpServletRequest;

// After (Spring Boot 3.x)
import jakarta.servlet.http.HttpServletRequest;

Search the codebase for remaining javax imports:

grep -R "javax" src/

Spring Security API change

// Old (Spring Security 5.x)
http.authorizeRequests().anyRequest().authenticated();

// New (Spring Security 6.x)
http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/api/**").authenticated()
);

JPA package rename

javax.persistence
jakarta.persistence

CI Setup (GitHub Actions)

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

Typical Components to Review

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

Common Errors and Fixes

Upgrade Checklist

• Java 8 → 11
• Fix removed Java EE modules
• Java 11 → 17
• Update CI pipeline to use JDK 17
• Upgrade Spring Boot 2.1 → 2.7
• Remove deprecated Spring APIs
• Upgrade Spring Boot 2.7 → 3.x
• Migrate javax.* packages to jakarta.*
• Update Spring Security configuration
• Replace Springfox with springdoc‑openapi
• Update Hibernate / JPA dependencies
• Run full integration tests

Following this phased approach—starting with Java 8 → 11, fixing deprecated APIs early, and testing thoroughly—will make the upgrade to Java 17 and Spring Boot 3.x smooth and low‑risk.