Java 17 Migration Guide (11→17)

// This code compiled and ran on Java 11 with a warning
// On Java 17, it throws InaccessibleObjectException
var field = String.class.getDeclaredField("value");
field.setAccessible(true); // FAILS on Java 17

// Fix: Use --add-opens as a temporary workaround
// java --add-opens java.base/java.lang=ALL-UNNAMED -jar app.jar

// Better fix: Stop using internal APIs and use public alternatives

// 1. Stricter JAR signature validation
// Java 17 rejects JARs signed with SHA-1 by default
// Fix: Re-sign JARs with SHA-256 or stronger

// 2. Default charset change (Java 18 heads-up)
// Java 17 still uses platform-specific default charset
// But Java 18 defaults to UTF-8. Start using explicit charsets now:
Files.readString(path, StandardCharsets.UTF_8);  // explicit -- always safe
Files.readString(path);  // uses platform default -- risky

// 3. DatagramSocket reimplementation (Java 15+)
// The underlying implementation of DatagramSocket was rewritten
// Unlikely to affect most apps, but test network code thoroughly

<!-- Run Maven dependency analysis -->
<!-- mvn versions:display-dependency-updates -->
<!-- mvn versions:display-plugin-updates -->

<!-- Check for internal API usage with jdeps -->
<!-- jdeps --jdk-internals -cp 'libs/*' your-app.jar -->
<!-- This shows which internal APIs your code and dependencies use -->

<!-- Maven: Update compiler plugin -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <release>17</release>
    </configuration>
</plugin>

<!-- Maven: Update surefire for testing -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.1.2</version>
</plugin>

# Using SDKMAN (recommended)
sdk install java 17.0.9-tem
sdk use java 17.0.9-tem

# Or download directly:
# - Eclipse Temurin: https://adoptium.net/
# - Amazon Corretto: https://aws.amazon.com/corretto/
# - Oracle JDK: https://www.oracle.com/java/

# Verify installation
java --version
# openjdk 17.0.9 2023-10-17
# OpenJDK Runtime Environment Temurin-17.0.9+9 (build 17.0.9+9)

# Set JAVA_HOME
export JAVA_HOME=$HOME/.sdkman/candidates/java/17.0.9-tem

// Error 1: Using removed APIs
// javax.script.ScriptEngine with Nashorn
// Fix: Remove Nashorn usage or add GraalJS dependency

// Error 2: Deprecated API warnings (promoted to errors)
// Fix: Replace deprecated APIs with recommended alternatives

// Error 3: Internal API access
// sun.misc.Unsafe, com.sun.*, etc.
// Fix: Use public API alternatives or --add-opens as temporary fix

// Error 4: New reserved keywords
// "sealed", "permits" are now restricted identifiers
// If you have variables named "sealed" or "permits", rename them
String sealed = "value"; // Compile error in Java 17 if used as type name

# Scan your application for JDK internal API usage
jdeps --jdk-internals --multi-release 17 -cp 'lib/*' your-app.jar

# Sample output:
# your-app.jar -> java.base
#   com.example.MyClass -> sun.misc.Unsafe (JDK internal API)
#
# Warning: JDK internal APIs are unsupported and private to JDK implementation
# that are subject to be removed or changed incompatibly and could break your
# application.
#
# JDK Internal API                Suggested Replacement
# ----------------                ---------------------
# sun.misc.Unsafe                 Use VarHandle or MethodHandle API

<!-- Maven surefire plugin configuration -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <argLine>
            --add-opens java.base/java.lang=ALL-UNNAMED
            --add-opens java.base/java.lang.reflect=ALL-UNNAMED
            --add-opens java.base/java.util=ALL-UNNAMED
        </argLine>
    </configuration>
</plugin>

<!-- For the application itself -->
<!-- Add to JVM startup args in your run script or Dockerfile -->
<!-- java --add-opens java.base/java.lang=ALL-UNNAMED -jar app.jar -->

# Compare GC performance between Java 11 and Java 17
# Run your application with GC logging enabled

# Java 17 with G1GC (default)
java -Xlog:gc*:file=gc-java17.log -jar app.jar

# Key improvements in Java 17 GC:
# - G1GC: Reduced pause times, better throughput
# - ZGC: Production-ready, sub-millisecond pauses (Java 15+)
# - Shenandoah: Production-ready, low-pause concurrent GC

# Consider switching GC if applicable:
# java -XX:+UseZGC -jar app.jar          # Ultra-low pause times
# java -XX:+UseShenandoahGC -jar app.jar # Low-pause alternative

// Priority 1: Use text blocks for multi-line strings (immediate wins)
// Before
String sql = "SELECT u.id, u.name, u.email\n" +
             "FROM users u\n" +
             "WHERE u.active = true\n" +
             "ORDER BY u.name";

// After
String sql = """
    SELECT u.id, u.name, u.email
    FROM users u
    WHERE u.active = true
    ORDER BY u.name
    """;

// Priority 2: Use pattern matching instanceof (reduce casting)
// Before
if (obj instanceof String) {
    String s = (String) obj;
    System.out.println(s.length());
}

// After
if (obj instanceof String s) {
    System.out.println(s.length());
}

// Priority 3: Use switch expressions where appropriate
// Before
String label;
switch (status) {
    case ACTIVE:   label = "Active";   break;
    case INACTIVE: label = "Inactive"; break;
    case PENDING:  label = "Pending";  break;
    default:       label = "Unknown";
}

// After
String label = switch (status) {
    case ACTIVE   -> "Active";
    case INACTIVE -> "Inactive";
    case PENDING  -> "Pending";
};

// Priority 4: Use records for new DTOs and value objects
// Priority 5: Use sealed classes for new type hierarchies

<!-- pom.xml updates for Java 17 -->
<properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <!-- Or use release (preferred, ensures API compatibility) -->
    <maven.compiler.release>17</maven.compiler.release>
</properties>

<build>
    <plugins>
        <!-- Compiler plugin: 3.11+ required for Java 17 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <release>17</release>
            </configuration>
        </plugin>

        <!-- Surefire: 3.x for proper Java 17 support -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.1.2</version>
        </plugin>

        <!-- Failsafe (integration tests) -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-failsafe-plugin</artifactId>
            <version>3.1.2</version>
        </plugin>

        <!-- JAR plugin -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.3.0</version>
        </plugin>
    </plugins>
</build>

// build.gradle updates for Java 17
// Gradle 7.3+ is required for Java 17 support

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0' // if using Spring Boot
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

tasks.withType(JavaCompile).configureEach {
    options.release = 17
}

// For Kotlin DSL (build.gradle.kts)
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

// Key Spring Boot 3.x changes:
// 1. javax.* -> jakarta.* namespace migration
//    javax.persistence.* -> jakarta.persistence.*
//    javax.servlet.*     -> jakarta.servlet.*
//    javax.validation.*  -> jakarta.validation.*
//    javax.annotation.*  -> jakarta.annotation.*

// Before (Spring Boot 2.x / Java 11)
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.servlet.http.HttpServletRequest;
import javax.validation.constraints.NotNull;

// After (Spring Boot 3.x / Java 17)
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.constraints.NotNull;

// Step 1: Run ALL existing unit tests on Java 17
// If tests fail, categorize the failures:
// - Compilation error -> fix source code
// - Runtime error -> update dependencies or add --add-opens
// - Behavior change -> investigate and update test expectations

// Step 2: Add tests for any workarounds
@Test
void testReflectiveAccessWorkaround() {
    // If you added --add-opens, test that the workaround works
    assertDoesNotThrow(() -> {
        // Code that requires reflective access
    });
}

// Step 3: Verify serialization compatibility
@Test
void testSerializationBackwardCompatibility() {
    // Deserialize objects that were serialized on Java 11
    byte[] java11Serialized = loadFromFile("test-data/user-java11.ser");
    User user = deserialize(java11Serialized);
    assertEquals("John", user.getName());
}

# Before (Java 11)
FROM eclipse-temurin:11-jre-alpine
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

# After (Java 17)
FROM eclipse-temurin:17-jre-alpine
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

# Multi-stage build for smaller images
FROM eclipse-temurin:17-jdk-alpine AS build
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn clean package -DskipTests

FROM eclipse-temurin:17-jre-alpine
COPY --from=build /app/target/app.jar /app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

# With --add-opens if needed
ENTRYPOINT ["java", \
    "--add-opens", "java.base/java.lang=ALL-UNNAMED", \
    "-jar", "/app.jar"]

# GitHub Actions example
name: Build and Test
on: [push, pull_request]

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

      - name: Set up Java 17
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Build and test
        run: mvn clean verify

      # Optional: Test on both Java 11 and 17 during migration
  compatibility-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        java-version: [11, 17]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: ${{ matrix.java-version }}
      - run: mvn clean verify