Java 21 Migration Guide (17→21)

// This code behaves DIFFERENTLY on Java 21 vs Java 17 (on Windows)
// Before Java 18: uses platform default (e.g., Windows-1252)
// Java 18+: uses UTF-8
String content = Files.readString(Path.of("data.txt")); // Now always UTF-8

// FIX: Be explicit about charset (you should have been doing this all along)
String content = Files.readString(Path.of("data.txt"), StandardCharsets.UTF_8);

// Or, if you truly need the old behavior:
String content = Files.readString(Path.of("data.txt"), Charset.forName("windows-1252"));

// BAD: This pattern is deprecated for removal
public class ResourceHolder {
    @Override
    protected void finalize() throws Throwable {
        // cleanup resources
        super.finalize();
    }
}

// GOOD: Use try-with-resources and AutoCloseable instead
public class ResourceHolder implements AutoCloseable {
    @Override
    public void close() {
        // cleanup resources
    }
}

// Or use Cleaner for cases where try-with-resources is not practical
public class ResourceHolder {
    private static final Cleaner cleaner = Cleaner.create();

    ResourceHolder() {
        cleaner.register(this, () -> {
            // cleanup action
        });
    }
}

// WARNING: A Java agent has been loaded dynamically...
// WARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading

// FIX: Add this JVM flag to suppress the warning (for now)
// java -XX:+EnableDynamicAgentLoading -jar myapp.jar

// Or, better: load agents at startup instead of dynamically
// java -javaagent:myagent.jar -jar myapp.jar

// PREVIEW syntax (Java 17-20) -- NO LONGER VALID
String result = switch (obj) {
    case String s && s.length() > 5 -> "long string";  // OLD syntax
    default -> "other";
};

// FINAL syntax (Java 21) -- USE THIS
String result = switch (obj) {
    case String s when s.length() > 5 -> "long string"; // NEW: 'when' keyword
    default -> "other";
};

# Linux/macOS
export JAVA_HOME=/path/to/jdk-21
export PATH=$JAVA_HOME/bin:$PATH

# Verify
java -version
# openjdk version "21.0.2" 2024-01-16 LTS

# Windows (PowerShell)
$env:JAVA_HOME = "C:\Program Files\Java\jdk-21"
$env:Path = "$env:JAVA_HOME\bin;$env:Path"

# Maven
mvn clean compile -DskipTests

# Gradle
./gradlew compileJava

# Note ALL warnings -- especially:
# - Deprecation warnings (finalize, SecurityManager, etc.)
# - Access warnings (illegal reflective access)
# - Preview feature usage from Java 17

    21
    21
    21




    
        
            org.apache.maven.plugins
            maven-compiler-plugin
            3.12.1
            
                21
                
                
            
        

        
        
            org.apache.maven.plugins
            maven-surefire-plugin
            3.2.3
            
                
                
            
        

        
        
            org.apache.maven.plugins
            maven-jar-plugin
            3.3.0
        
    

// build.gradle (Groovy DSL)
plugins {
    id 'java'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

// Or set source/target compatibility directly
sourceCompatibility = JavaVersion.VERSION_21
targetCompatibility = JavaVersion.VERSION_21

// For preview features:
tasks.withType(JavaCompile).configureEach {
    options.compilerArgs += ['--enable-preview']
}

tasks.withType(Test).configureEach {
    jvmArgs += ['--enable-preview']
}

tasks.withType(JavaExec).configureEach {
    jvmArgs += ['--enable-preview']
}

// build.gradle.kts (Kotlin DSL)
plugins {
    java
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}

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



    21

// Error:
// java.lang.reflect.InaccessibleObjectException:
// Unable to make field private final byte[] java.lang.String.value accessible:
// module java.base does not "opens java.lang" to unnamed module

// Fix: Add --add-opens to your JVM startup flags
// java --add-opens java.base/java.lang=ALL-UNNAMED -jar myapp.jar

// Common --add-opens needed for popular libraries:
// --add-opens java.base/java.lang=ALL-UNNAMED          (Byte Buddy, Mockito)
// --add-opens java.base/java.lang.reflect=ALL-UNNAMED   (Spring, Hibernate)
// --add-opens java.base/java.util=ALL-UNNAMED            (Various libraries)
// --add-opens java.base/java.io=ALL-UNNAMED              (Serialization libraries)
// --add-opens java.base/sun.nio.ch=ALL-UNNAMED           (Netty)

# Enable Generational ZGC
java -XX:+UseZGC -XX:+ZGenerational -jar myapp.jar

# In Java 23+, ZGenerational is the default when using ZGC
# For Java 21, you must explicitly enable it

# Compare GC performance:
# Run your app with G1GC (default) and monitor
java -XX:+UseG1GC -Xlog:gc -jar myapp.jar

# Then run with Generational ZGC and compare
java -XX:+UseZGC -XX:+ZGenerational -Xlog:gc -jar myapp.jar

# BEFORE: Java 17 Dockerfile
FROM eclipse-temurin:17-jre-alpine
COPY target/myapp.jar /app/myapp.jar
ENTRYPOINT ["java", "-jar", "/app/myapp.jar"]

# AFTER: Java 21 Dockerfile
FROM eclipse-temurin:21-jre-alpine
COPY target/myapp.jar /app/myapp.jar
ENTRYPOINT ["java", "-jar", "/app/myapp.jar"]

# RECOMMENDED: Multi-stage build with Java 21
FROM eclipse-temurin:21-jdk-alpine AS build
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN apk add --no-cache maven && mvn clean package -DskipTests

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=build /app/target/myapp.jar ./myapp.jar

# Optimized JVM flags for containers
ENTRYPOINT ["java", \
    "-XX:+UseZGC", \
    "-XX:+ZGenerational", \
    "-XX:MaxRAMPercentage=75.0", \
    "-XX:+UseContainerSupport", \
    "-jar", "myapp.jar"]

# GraalVM native image with Java 21
# Install GraalVM for JDK 21
sdk install java 21.0.2-graalce

# Build native image (Spring Boot with Spring Native / GraalVM)
./mvnw -Pnative native:compile

# Or with Gradle
./gradlew nativeCompile

# Important: Virtual threads work in native images since GraalVM for JDK 21
# But some preview features may not be supported in native image mode

# GitHub Actions: .github/workflows/build.yml
name: Build and Test

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Build with Maven
        run: mvn clean verify

      - name: Build Docker image
        run: docker build -t myapp:latest .

// Week 1-2: Upgrade JDK and build tools, fix compilation issues
// Week 3-4: Run full test suite, fix failures
// Week 5-6: Deploy to staging, run integration tests
// Week 7-8: Deploy to production (canary)
// Week 9+: Start adopting new language features in new code

// Example: Adopting pattern matching for switch gradually
// BEFORE (Java 17 style)
public String describe(Object obj) {
    if (obj instanceof String s) {
        return "String of length " + s.length();
    } else if (obj instanceof Integer i) {
        return "Integer: " + i;
    } else if (obj instanceof List list) {
        return "List with " + list.size() + " elements";
    } else {
        return "Unknown: " + obj.getClass().getSimpleName();
    }
}

// AFTER (Java 21 style -- pattern matching for switch)
public String describe(Object obj) {
    return switch (obj) {
        case String s       -> "String of length " + s.length();
        case Integer i      -> "Integer: " + i;
        case List list   -> "List with " + list.size() + " elements";
        case null           -> "null";
        default             -> "Unknown: " + obj.getClass().getSimpleName();
    };
}

// BEFORE (Java 17): Getting first/last elements was awkward
List names = List.of("Alice", "Bob", "Charlie");

// First element
String first = names.get(0);                    // works but ugly for other collections
String first2 = names.iterator().next();         // generic but verbose

// Last element
String last = names.get(names.size() - 1);       // error-prone
// For LinkedList: ((LinkedList)names).getLast(); // casting!

// AFTER (Java 21): Sequenced collections make it clean
SequencedCollection names = List.of("Alice", "Bob", "Charlie");

String first = names.getFirst();    // "Alice" -- works on ALL SequencedCollections
String last  = names.getLast();     // "Charlie" -- clean, universal

// Reverse view (no copying!)
SequencedCollection reversed = names.reversed();
// reversed: ["Charlie", "Bob", "Alice"]

// Works on Sets too (LinkedHashSet, TreeSet)
SequencedSet orderedSet = new LinkedHashSet<>(List.of("X", "Y", "Z"));
orderedSet.getFirst();  // "X"
orderedSet.getLast();   // "Z"

// Works on Maps (LinkedHashMap, TreeMap)
SequencedMap map = new LinkedHashMap<>();
map.put("first", 1);
map.put("second", 2);
map.put("third", 3);

map.firstEntry();  // "first"=1
map.lastEntry();   // "third"=3
map.reversed();    // reversed view of the map