Skip to content

Java Version Migration Guide

Status: 🟢 Active  |  Owner: Java Guild

Migration Path

The supported migration path is: Java 11 → Java 17 → Java 21.

Skipping versions is permitted (11 → 21 directly), but requires validating against all breaking changes in intermediate releases.

Java 17 → 21 Migration

This is the current priority migration for teams on Java 17.

Key Changes

Virtual Threads (Project Loom) — opt-in via Spring Boot 3.2+. No code changes required to enable; see JVM Tuning.

Sequenced Collections — new interfaces (SequencedCollection, SequencedMap) are now in the type hierarchy of List, LinkedHashMap, etc. Compilation may warn if you have custom classes implementing these interfaces without the new methods.

Pattern Matching in Switch — finalised in Java 21. Existing switch statements are unaffected; adoption is incremental.

Migration Steps

  1. Update build toolchain to declare Java 21 target (see Build Tooling).
  2. Run ./gradlew build — fix compilation errors.
  3. Run full test suite including integration tests.
  4. Check for third-party library compatibility (especially Mockito, Hibernate, Byte Buddy).
  5. Update the base Docker image to eclipse-temurin:21-jre-alpine.
  6. Enable virtual threads in staging and validate under load.

Java 11 → 17 Migration

Removed APIs

Removed Replacement
sun.misc.BASE64Encoder java.util.Base64
Applet API N/A (not applicable to services)
Security Manager N/A (not used)

Sealed Classes (Java 17)

If your codebase uses sealed as an identifier name (method, variable), it must be renamed — sealed is now a restricted identifier.

Strong Encapsulation

From Java 17, many internal JDK APIs are strongly encapsulated. Common violations:

InaccessibleObjectException: Unable to make ... accessible

Fix by migrating away from the internal API, or add --add-opens as a temporary workaround while refactoring.

Dependency Compatibility Checklist

Before migrating, verify:

  • Spring Boot: 3.2.x required for Java 21 support.
  • Mockito: 5.x required for Java 21.
  • Hibernate: 6.x required for Java 17+.
  • Byte Buddy (used by Mockito/Hibernate): check compatible version matrix.
  • Any reflection-heavy libraries (MapStruct, Lombok): verify compatibility.

References

Last reviewed: 2025-Q4  |  Owner: Java Guild