ADR-004: Migrate to Spring Boot 3.x

Decision Analysis and Resolution: Spring Boot Version Migration

Created by: SW360 Architecture Team
Original Decision: 2024
Reformatted: April 2026
Status: Accepted
Estimated read time: 10 minutes

Table of Contents

1. Background
2. Goal
3. Key Principles
4. Key Inputs, Assumptions and Restrictions
5. Options Analysis
   • Option 1 - Stay on Spring Boot 2.7.x
   • Option 2 - Migrate to Spring Boot 3.x
   • Option 3 - Alternative Framework Migration
6. Criteria for Making a Decision
7. Final Decision
8. Migration Effort
9. Contributors

Background

SW360’s REST API was built on Spring Boot 2.x with Spring Security 5.x. Several factors drove the need to evaluate migration:

1. End of Life: Spring Boot 2.x reached end of commercial support in November 2024
2. Security Updates: Spring Security 6.x includes important security improvements
3. Java Evolution: Spring Boot 3.x fully supports Java 21 features (virtual threads, records)
4. Jakarta EE: Industry migration from javax.* to jakarta.* namespace
5. Dependency Ecosystem: Many libraries dropping Spring Boot 2.x support

Migration Scope:

• Spring Boot 2.7.x → 3.5.x
• Spring Security 5.x → 6.5.x
• Java 11 → Java 21
• javax.* → jakarta.*

Goal

The goal of this decision analysis is to:

1. Determine whether to migrate SW360 REST API to Spring Boot 3.x
2. Evaluate migration effort versus staying on unsupported version
3. Identify risks and mitigation strategies
4. Plan migration phases if proceeding

Key Principles

Key Inputs, Assumptions and Restrictions

Options Analysis

Option 1 - Stay on Spring Boot 2.7.x

Summary

Continue using Spring Boot 2.7.x indefinitely, accepting that security patches and updates will no longer be provided. Monitor for critical vulnerabilities and patch manually if necessary.

Conceptual View

graph TB
    subgraph SB2["Spring Boot 2.7.x (EOL)"]
        direction TB
        A1["+ Spring Security 5.x"]
        A2["+ Java 11/17"]
        A3["+ javax.* namespace"]
        A4["- No security patches after Nov 2024"]
        A5["- Shrinking dependency compatibility"]
    end

Impact / Changes Required

• No code changes required
• Monitor security advisories manually
• Fork and patch dependencies if vulnerabilities discovered
• Accept increasing technical debt

SWOT Analysis

Option 2 - Migrate to Spring Boot 3.x

Summary

Migrate SW360 REST API to Spring Boot 3.5.x with Java 21, including the namespace migration from javax.* to jakarta.* and Spring Security configuration updates.

Conceptual View

graph TB
    subgraph SB3["Spring Boot 3.5.x (Active)"]
        direction TB
        B1["+ Spring Security 6.5.x"]
        B2["+ Java 21 (virtual threads, records)"]
        B3["+ jakarta.* namespace"]
        B4["+ Active security patches"]
        B5["+ Modern ecosystem support"]
    end

Impact / Changes Required

• Namespace migration: javax.* → jakarta.*
• Spring Security configuration rewrite
• OpenAPI/SpringDoc version upgrade
• Test updates for new APIs
• Full regression testing

SWOT Analysis

Option 3 - Alternative Framework Migration

Summary

Instead of migrating Spring Boot versions, consider migrating to an alternative framework such as Quarkus, Micronaut, or Helidon that offers native compilation and modern features.

Conceptual View

graph TB
    subgraph QM["Quarkus / Micronaut"]
        direction TB
        C1["+ Native compilation (GraalVM)"]
        C2["+ Fast startup, low memory"]
        C3["+ Modern reactive programming"]
        C4["- Complete rewrite required"]
        C5["- Different programming model"]
    end

Impact / Changes Required

• Complete REST API rewrite
• New annotations, dependency injection
• Different testing frameworks
• Team retraining

SWOT Analysis

Criteria for Making a Decision

T-Shirt Sizing Scale

Weighted Evaluation Matrix

Score Summary

Final Decision

Selected Option: Migrate to Spring Boot 3.5.x with Java 21

Rationale

Migration to Spring Boot 3.x was selected based on:

1. Highest Weighted Score (647.5) - Best balance of effort versus benefit

2. Security Patches (XL) - Critical requirement:

   • Active vulnerability fixes
   • Compliance audit requirements
   • CVE response SLA

3. Long-term Support (L-XL) - Spring Boot 3.x will be maintained for years

4. Java 21 Features (XL) - Significant improvements:

   • Virtual threads for improved scalability
   • Records for cleaner data classes
   • Pattern matching for cleaner code
   • Better garbage collection

5. Ecosystem Alignment (L-XL) - Libraries are migrating to Jakarta EE

Migration Effort

Effort Estimation by Area

Key Code Changes

1. Namespace Migration

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

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

2. Security Configuration

// Before (Spring Boot 2.x)
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/api/**").authenticated()
            .and()
            .oauth2ResourceServer().jwt();
    }
}

// After (Spring Boot 3.x)
@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/**").authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
        return http.build();
    }
}

3. OpenAPI/SpringDoc

<!-- Before -->
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.x</version>

<!-- After -->
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.x</version>

Version Matrix

Review Triggers

This decision should be revisited if:

• Spring Boot 4.x is released with significant benefits
• Critical dependency incompatibility is discovered
• Performance regression is unacceptable

Contributors

Consequences Summary

Positive

• ✅ Supported platform—active security patches and updates
• ✅ Java 21 features—records, virtual threads, better performance
• ✅ Modern OAuth2—improved resource server configuration
• ✅ Better tooling—latest IDE support and debugging
• ✅ Dependency updates—access to latest library versions
• ✅ Compliance—meets security audit requirements

Negative

• ⚠️ Breaking changes—significant code modifications required
• ⚠️ Testing effort—full regression testing needed
• ⚠️ Learning curve—new security configuration patterns
• ⚠️ Compatibility—some older libraries may not support Spring Boot 3

Technical Debt Addressed

• Removed deprecated APIs
• Modernized security configuration
• Updated to supported Java LTS version

Revision History