Upgrade to Spring Boot 4.0 and JDK 25 LTS

[nanotaboada]

Description

The project currently uses Spring Boot 3.4.4 and JDK 21 (LTS). Spring Boot 4.0.0 was released on November 20, 2025 with support for JDK 25 LTS (released September 2025). This issue tracks the upgrade to the latest LTS versions of both Spring Boot and the JDK.

Current Configuration

Maven POM (pom.xml):

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.4</version>
</parent>

<properties>
    <java.version>21</java.version>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
</properties>

Docker (Dockerfile):

FROM eclipse-temurin:21-jdk-alpine AS build
FROM eclipse-temurin:21-jre-alpine AS runtime

Why Upgrade?

Spring Boot 4.0 Key Features:

• Native support for JDK 25 LTS
• Jakarta EE 11 baseline (upgraded from EE 10)
• Spring Framework 7.0 foundation
• Enhanced observability and metrics
• Improved performance and memory efficiency
• Migration to org.springframework.boot.test.mock.mockito.MockBean deprecation (replaced with standard Mockito)

JDK 25 LTS Benefits:

• Latest LTS with long-term support until 2032
• Performance improvements and security patches
• New language features (pattern matching enhancements, structured concurrency, etc.)
• Better garbage collection improvements
• Generational ZGC and Shenandoah enhancements

Proposed Solution

Perform a coordinated upgrade of Spring Boot and JDK in a single migration:

1. Update to Spring Boot 4.0.0 (or latest 4.x)
2. Update to JDK 25 LTS
3. Fix breaking changes (Jakarta EE 11, deprecated APIs)
4. Update Docker images to JDK 25
5. Update CI/CD pipelines
6. Update documentation
7. Test thoroughly

Migration Checklist

1. Update Spring Boot Version

pom.xml:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.0</version> <!-- or latest 4.x -->
</parent>

<properties>
    <java.version>25</java.version>
    <maven.compiler.source>25</maven.compiler.source>
    <maven.compiler.target>25</maven.compiler.target>
</properties>

2. Update Test Annotations

Spring Boot 4.0 deprecates @MockBean in favor of standard Mockito @MockitoBean:

Before (Spring Boot 3.x):

import org.springframework.boot.test.mock.mockito.MockBean;

@WebMvcTest(BooksController.class)
class BooksControllerTests {
    @MockBean
    private BooksService booksServiceMock;
}

After (Spring Boot 4.0):

import org.springframework.test.context.bean.override.mockito.MockitoBean;

@WebMvcTest(BooksController.class)
class BooksControllerTests {
    @MockitoBean
    private BooksService booksServiceMock;
}

Files to update:

• BooksControllerTests.java - Replace @MockBean with @MockitoBean
• BooksServiceTests.java - Use standard Mockito @Mock and @InjectMocks (no changes needed)

3. Update Docker Configuration

Dockerfile:

FROM eclipse-temurin:25-jdk-alpine AS build
WORKDIR /workspace/app

COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
COPY src src

RUN ./mvnw package -DskipTests
RUN mkdir -p target/dependency && (cd target/dependency; jar -xf ../*.jar)

FROM eclipse-temurin:25-jre-alpine AS runtime
VOLUME /tmp
ARG DEPENDENCY=/workspace/app/target/dependency
COPY --from=build ${DEPENDENCY}/BOOT-INF/lib /app/lib
COPY --from=build ${DEPENDENCY}/META-INF /app/META-INF
COPY --from=build ${DEPENDENCY}/BOOT-INF/classes /app
ENTRYPOINT ["java","-cp","app:app/lib/*","ar.com.nanotaboada.java.samples.spring.boot.Application"]

4. Update CI/CD Pipelines

GitHub Actions (.github/workflows/maven.yml):

- name: Set up JDK 25
  uses: actions/setup-java@v4
  with:
    java-version: '25'
    distribution: 'temurin'

Azure Pipelines (azure-pipelines.yml):

- task: JavaToolInstaller@0
  inputs:
    versionSpec: '25'
    jdkArchitectureOption: 'x64'
    jdkSourceOption: 'PreInstalled'

5. Review Dependency Versions

Check and update versions for Spring Boot 4.0 compatibility:

• Lombok - Verify JDK 25 annotation processing works (update to 1.18.36+)
• SpringDoc OpenAPI - Update to version compatible with Spring Boot 4.0
• ModelMapper - Verify compatibility
• JaCoCo - Verify bytecode instrumentation works with class version 69 (JDK 25)
• Mockito - Should be managed by Spring Boot 4.0 (verify version supports JDK 25)

6. Update Documentation

Files to update:

• .github/copilot-instructions.md - Change all JDK 21 / Spring Boot 3.x references
• README.md - Update Prerequisites section (JDK 25, Spring Boot 4.0)
• CONTRIBUTING.md - Update development setup instructions
• pom.xml - Update <description> if it mentions Spring Boot 3

Key sections:

• Prerequisites: "JDK 25 (LTS) required"
• Stack: "Spring Boot 4.0"
• Troubleshooting: Update JAVA_HOME examples
• Build commands: Verify Maven wrapper works with JDK 25

7. Testing Strategy

• Run full test suite: ./mvnw verify
• Verify all 32+ tests pass
• Check JaCoCo coverage reports generate correctly
• Test Docker build: docker compose build
• Test Docker run: docker compose up
• Verify Swagger UI: http://localhost:9000/swagger/index.html
• Verify Actuator: http://localhost:9001/actuator/health
• Run application locally: ./mvnw spring-boot:run
• Test all CRUD endpoints + search endpoint
• Performance testing (compare before/after)

Breaking Changes to Address

Jakarta EE 11 Namespace Changes

Spring Boot 4.0 moves to Jakarta EE 11. Most imports should remain the same (jakarta.*), but verify:

• jakarta.validation - Bean Validation 3.1
• jakarta.persistence - JPA 3.2
• jakarta.servlet - Servlet 6.1

Deprecated APIs

Review Spring Boot 4.0 migration guide for deprecated APIs:

• @MockBean → @MockitoBean (already noted above)
• Check for any other deprecations in controller/service layers

Configuration Properties

Review application.properties for any deprecated property keys and update to new names per Spring Boot 4.0 migration guide.

Acceptance Criteria

• All Maven builds pass with JDK 25: ./mvnw clean verify
• All 32+ unit tests pass without errors or warnings
• Test coverage remains at 100% for controller and service layers
• Docker image builds successfully with JDK 25 base images
• Application runs without errors on Spring Boot 4.0 + JDK 25
• GitHub Actions CI pipeline passes
• Swagger UI works correctly
• Actuator endpoints respond correctly
• Documentation updated to reflect Spring Boot 4.0 and JDK 25
• No performance regressions (benchmark if needed)
• All CRUD endpoints + search endpoint function correctly

Edge Cases & Risks

1. Mockito Agent Loading Warnings

Current behavior (JDK 21):

WARNING: A Java agent has been loaded dynamically
WARNING: Dynamic loading of agents will be disallowed by default in a future release

Risk: JDK 25 may enforce stricter agent loading policies
Mitigation:

• Follow Spring Boot 4.0 guidance on Mockito configuration
• Consider adding Mockito agent to Maven Surefire plugin configuration
• Use @MockitoBean instead of @MockBean

2. CLOB Handling in H2

Current: Using CAST(description AS string) in JPQL for H2 CLOB fields
Risk: H2 database version bundled with Spring Boot 4.0 may behave differently
Mitigation:

• Test search endpoint thoroughly
• Review H2 version changes in Spring Boot 4.0 release notes
• Consider Issue Consider migrating database from H2 to SQLite #80 (H2 → SQLite migration) as future work

3. Third-Party Dependency Compatibility

Risk: Some dependencies may not yet support Spring Boot 4.0
Mitigation:

• Check SpringDoc OpenAPI compatibility before upgrade
• Review ModelMapper for Spring Boot 4.0 support
• Have rollback plan ready

4. Docker Image Size

Risk: JDK 25 images may be larger than JDK 21
Mitigation:

• Monitor image size after upgrade
• Consider using -alpine variants
• Optimize layer caching in Dockerfile

Rollback Plan

If Spring Boot 4.0 + JDK 25 causes issues:

1. Revert pom.xml to Spring Boot 3.4.4 and JDK 21
2. Revert test annotations (@MockitoBean → @MockBean)
3. Revert Dockerfile to eclipse-temurin:21 images
4. Revert CI/CD pipeline configurations
5. Revert documentation changes
6. Rebuild and redeploy: ./mvnw clean package

Rollback Trigger Conditions:

• Test failures that cannot be resolved within reasonable time
• Critical dependency incompatibilities with no workaround
• Performance degradation > 15%
• Production issues after deployment

Resources

• 🔗 Spring Boot 4.0 Release Notes
• 🔗 Spring Boot 4.0 Migration Guide
• 🔗 JDK 25 Release Notes
• 🔗 Eclipse Temurin 25 Announcement
• 🔗 Jakarta EE 11 Specification
• 🔗 Spring Framework 7.0 What's New

Related Issues

• Consider migrating database from H2 to SQLite #80 - Database migration (H2 → SQLite) - can be done after this upgrade
• Add new endpoint /books/search to handle search by description #128 - Book search endpoint - already implemented, needs testing with Spring Boot 4.0

Implementation Order

Since you have no rush to implement #128 (search endpoint is already complete), the recommended order is:

1. This Issue (Upgrade to Spring Boot 4.0 and JDK 25 LTS #232) - Upgrade to Spring Boot 4.0 + JDK 25 FIRST
2. Issue Add new endpoint /books/search to handle search by description #128 - Already implemented, just needs final testing after this upgrade

This ensures the codebase is on the latest LTS stack before completing the search endpoint work.

---

Status: 🟢 Ready to implement - Both Spring Boot 4.0 and JDK 25 LTS are released and stable