java-17-to-java-21-upgrade

name	java-17-to-java-21-upgrade
description	Upgrade guidance for moving TRUE Connector code and build configuration from Java 17 to Java 21, covering modern language features, concurrency updates, and migration considerations.

Java 17 to Java 21 Upgrade Guide

Purpose

Use this skill when a task upgrades Java language usage, build settings, or runtime behavior from Java 17 to Java 21.

The detailed guidance below was adapted from .github/instructions/java-17-to-java-21-upgrade.instructions.md.

Use this skill when

• A task upgrades the project or a module from Java 17 to Java 21.
• You are evaluating Java 21 language or library features for code modernization.
• You need guidance on virtual threads, preview features, or post-upgrade build and test configuration.

Instructions for Copilot

1. Prefer standard Java 21 features first and label preview features clearly as optional or gated.
2. Call out concurrency, GC, or preview-feature changes separately from routine syntax modernizations.
3. Update compiler, test, and runtime configuration together when enabling new platform capabilities.

These instructions help GitHub Copilot assist developers in upgrading Java projects from JDK 17 to JDK 21, focusing on new language features, API changes, and best practices.

Major Language Features in JDK 18-21

Pattern Matching for switch (JEP 441 - Standard in 21)

Enhanced switch Expressions and Statements

When working with switch constructs:

• Suggest converting traditional switch to pattern matching where appropriate
• Use pattern matching for type checking and destructuring
• Example upgrade patterns:

// Old approach (Java 17)
public String processObject(Object obj) {
    if (obj instanceof String) {
        String s = (String) obj;
        return s.toUpperCase();
    } else if (obj instanceof Integer) {
        Integer i = (Integer) obj;
        return i.toString();
    }
    return "unknown";
}

// New approach (Java 21)
public String processObject(Object obj) {
    return switch (obj) {
        case String s -> s.toUpperCase();
        case Integer i -> i.toString();
        case null -> "null";
        default -> "unknown";
    };
}

• Support guarded patterns:

switch (obj) {
    case String s when s.length() > 10 -> "Long string: " + s;
    case String s -> "Short string: " + s;
    case Integer i when i > 100 -> "Large number: " + i;
    case Integer i -> "Small number: " + i;
    default -> "Other";
}

Record Patterns (JEP 440 - Standard in 21)

Destructuring Records in Pattern Matching

When working with records:

• Suggest using record patterns for destructuring
• Combine with switch expressions for powerful data processing
• Example usage:

public record Point(int x, int y) {}
public record ColoredPoint(Point point, Color color) {}

// Destructuring in switch
public String describe(Object obj) {
    return switch (obj) {
        case Point(var x, var y) -> "Point at (" + x + ", " + y + ")";
        case ColoredPoint(Point(var x, var y), var color) -> 
            "Colored point at (" + x + ", " + y + ") in " + color;
        default -> "Unknown shape";
    };
}

• Use in complex pattern matching:

// Nested record patterns
switch (shape) {
    case Rectangle(ColoredPoint(Point(var x1, var y1), var c1), 
                   ColoredPoint(Point(var x2, var y2), var c2)) 
        when c1 == c2 -> "Monochrome rectangle";
    case Rectangle r -> "Multi-colored rectangle";
}

Virtual Threads (JEP 444 - Standard in 21)

Lightweight Concurrency

When working with concurrency:

• Suggest Virtual Threads for high-throughput, concurrent applications
• Use Thread.ofVirtual() for creating virtual threads
• Example migration patterns:

// Old platform thread approach
ExecutorService executor = Executors.newFixedThreadPool(100);
executor.submit(() -> {
    // blocking I/O operation
    httpClient.send(request);
});

// New virtual thread approach
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    executor.submit(() -> {
        // blocking I/O operation - now scales to millions
        httpClient.send(request);
    });
}

• Use structured concurrency patterns:

// Structured concurrency (Preview)
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
    Future<String> user = scope.fork(() -> fetchUser(userId));
    Future<String> order = scope.fork(() -> fetchOrder(orderId));
    
    scope.join();           // Join all subtasks
    scope.throwIfFailed();  // Propagate errors
    
    return processResults(user.resultNow(), order.resultNow());
}

String Templates (JEP 430 - Preview in 21)

Safe String Interpolation

When working with string formatting:

• Suggest String Templates for safe string interpolation (preview feature)
• Enable preview features with --enable-preview
• Example usage:

// Traditional concatenation
String message = "Hello, " + name + "! You have " + count + " messages.";

// String Templates (Preview)
String message = STR."Hello, \{name}! You have \{count} messages.";

// Safe HTML generation
String html = HTML."<p>User: \{username}</p>";

// Safe SQL queries  
PreparedStatement stmt = SQL."SELECT * FROM users WHERE id = \{userId}";

Sequenced Collections (JEP 431 - Standard in 21)

Enhanced Collection Interfaces

When working with collections:

• Use new SequencedCollection, SequencedSet, SequencedMap interfaces
• Access first/last elements uniformly across collection types
• Example usage:

// New methods available on Lists, Deques, LinkedHashSet, etc.
List<String> list = List.of("first", "middle", "last");
String first = list.getFirst();  // "first"
String last = list.getLast();    // "last"
List<String> reversed = list.reversed(); // ["last", "middle", "first"]

// Works with any SequencedCollection
SequencedSet<String> set = new LinkedHashSet<>();
set.addFirst("start");
set.addLast("end");
String firstElement = set.getFirst();

Unnamed Patterns and Variables (JEP 443 - Preview in 21)

Simplified Pattern Matching

When working with pattern matching:

• Use unnamed patterns _ for values you don't need
• Simplify switch expressions and record patterns
• Example usage:

// Ignore unused variables
switch (ball) {
    case RedBall(_) -> "Red ball";     // Don't care about size
    case BlueBall(var size) -> "Blue ball size " + size;
}

// Ignore parts of records
switch (point) {
    case Point(var x, _) -> "X coordinate: " + x; // Ignore Y
    case ColoredPoint(Point(_, var y), _) -> "Y coordinate: " + y;
}

// Exception handling with unnamed variables
try {
    riskyOperation();
} catch (IOException | SQLException _) {
    // Don't need exception details
    handleError();
}

Scoped Values (JEP 446 - Preview in 21)

Improved Context Propagation

When working with thread-local data:

• Consider Scoped Values as a modern alternative to ThreadLocal
• Better performance and clearer semantics for virtual threads
• Example usage:

// Define scoped value
private static final ScopedValue<String> USER_ID = ScopedValue.newInstance();

// Set and use scoped value
ScopedValue.where(USER_ID, "user123")
    .run(() -> {
        processRequest(); // Can access USER_ID.get() anywhere in call chain
    });

// In nested method
public void processRequest() {
    String userId = USER_ID.get(); // "user123"
    // Process with user context
}

API Enhancements and New Features

UTF-8 by Default (JEP 400 - Standard in 18)

When working with file I/O:

• UTF-8 is now the default charset on all platforms
• Remove explicit charset specifications where UTF-8 was intended
• Example simplification:

// Old explicit UTF-8 specification
Files.readString(path, StandardCharsets.UTF_8);
Files.writeString(path, content, StandardCharsets.UTF_8);

// New default behavior (Java 18+)
Files.readString(path);  // Uses UTF-8 by default
Files.writeString(path, content);  // Uses UTF-8 by default

Simple Web Server (JEP 408 - Standard in 18)

When needing basic HTTP server:

• Use built-in jwebserver command or com.sun.net.httpserver enhancements
• Great for testing and development
• Example usage:

// Command line
$ jwebserver -p 8080 -d /path/to/files

// Programmatic usage
HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
server.createContext("/", new SimpleFileHandler(Path.of("/tmp")));
server.start();

Internet-Address Resolution SPI (JEP 418 - Standard in 19)

When working with custom DNS resolution:

• Implement InetAddressResolverProvider for custom address resolution
• Useful for service discovery and testing scenarios

Key Encapsulation Mechanism API (JEP 452 - Standard in 21)

When working with post-quantum cryptography:

• Use KEM API for key encapsulation mechanisms
• Example usage:

KeyPairGenerator kpg = KeyPairGenerator.getInstance("ML-KEM");
KeyPair kp = kpg.generateKeyPair();

KEM kem = KEM.getInstance("ML-KEM");
KEM.Encapsulator encapsulator = kem.newEncapsulator(kp.getPublic());
KEM.Encapsulated encapsulated = encapsulator.encapsulate();

Deprecations and Warnings

Finalization Deprecation (JEP 421 - Deprecated in 18)

When encountering finalize() methods:

• Remove finalize methods and use alternatives
• Suggest Cleaner API or try-with-resources
• Example migration:

// Deprecated finalize approach
@Override
protected void finalize() throws Throwable {
    cleanup();
}

// Modern approach with Cleaner
private static final Cleaner CLEANER = Cleaner.create();

public MyResource() {
    cleaner.register(this, new CleanupTask(nativeResource));
}

private static class CleanupTask implements Runnable {
    private final long nativeResource;
    
    CleanupTask(long nativeResource) {
        this.nativeResource = nativeResource;
    }
    
    public void run() {
        cleanup(nativeResource);
    }
}

Dynamic Agent Loading (JEP 451 - Warnings in 21)

When working with agents or instrumentation:

• Add -XX:+EnableDynamicAgentLoading to suppress warnings if needed
• Consider loading agents at startup instead of dynamically
• Update tooling to use startup agent loading

Build Configuration Updates

Preview Features

For projects using preview features:

• Add --enable-preview to compiler and runtime
• Maven configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <release>21</release>
        <compilerArgs>
            <arg>--enable-preview</arg>
        </compilerArgs>
    </configuration>
</plugin>

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <argLine>--enable-preview</argLine>
    </configuration>
</plugin>

• Gradle configuration:

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

tasks.withType<JavaCompile> {
    options.compilerArgs.add("--enable-preview")
}

tasks.withType<Test> {
    jvmArgs("--enable-preview")
}

Virtual Threads Configuration

For applications using Virtual Threads:

• No special JVM flags required (standard feature in 21)
• Consider these system properties for debugging:

-Djdk.virtualThreadScheduler.parallelism=N  # Set carrier thread count
-Djdk.virtualThreadScheduler.maxPoolSize=N  # Set max pool size

Runtime and GC Improvements

Generational ZGC (JEP 439 - Available in 21)

When configuring garbage collection:

• Try Generational ZGC for better performance
• Enable with: -XX:+UseZGC -XX:+ZGenerational
• Monitor allocation patterns and GC behavior

Migration Strategy

Step-by-Step Upgrade Process

1. Update Build Tools: Ensure Maven/Gradle supports JDK 21
2. Language Feature Adoption:
   • Start with pattern matching for switch (standard)
   • Add record patterns where beneficial
   • Consider Virtual Threads for I/O heavy applications
3. Preview Features: Enable only if needed for specific use cases
4. Testing: Comprehensive testing especially for concurrency changes
5. Performance: Benchmark with new GC options

Code Review Checklist

When reviewing code for Java 21 upgrade:

• Convert appropriate instanceof chains to switch expressions
• Use record patterns for data destructuring
• Replace ThreadLocal with ScopedValues where appropriate
• Consider Virtual Threads for high-concurrency scenarios
• Remove explicit UTF-8 charset specifications
• Replace finalize() methods with Cleaner or try-with-resources
• Use SequencedCollection methods for first/last access patterns
• Add preview flags only for preview features in use

Common Migration Patterns

1. Switch Enhancement:

   // From instanceof chains to switch expressions
   if (obj instanceof String s) return processString(s);
   else if (obj instanceof Integer i) return processInt(i);
   // becomes:
   return switch (obj) {
       case String s -> processString(s);
       case Integer i -> processInt(i);
       default -> processDefault(obj);
   };
   

2. Virtual Thread Adoption:

   // From platform threads to virtual threads
   Executors.newFixedThreadPool(200)
   // becomes:
   Executors.newVirtualThreadPerTaskExecutor()
   

3. Record Pattern Usage:

   // From manual destructuring to record patterns
   if (point instanceof Point p) {
       int x = p.x();
       int y = p.y();
   }
   // becomes:
   if (point instanceof Point(var x, var y)) {
       // use x and y directly
   }
   

Performance Considerations

• Virtual Threads excel with blocking I/O but may not benefit CPU-intensive tasks
• Generational ZGC can reduce GC overhead for most applications
• Pattern matching in switch is generally more efficient than instanceof chains
• SequencedCollection methods provide O(1) access to first/last elements
• Scoped Values have lower overhead than ThreadLocal for virtual threads

Testing Recommendations

• Test Virtual Thread applications under high concurrency
• Verify pattern matching covers all expected cases
• Performance test with Generational ZGC vs other collectors
• Validate UTF-8 default behavior across different platforms
• Test preview features thoroughly before production use

Remember to enable preview features only when specifically needed and test thoroughly in staging environments before deploying to production.