Java 21 Upgrade — Executive Report

📋 Executive Summary

The java-dataloader library (a pure Java port of Facebook DataLoader, used as a core component in GraphQL Java execution pipelines) was successfully upgraded from Java 11 to Java 21. The upgrade was performed using OpenRewrite's automated migration recipe (com.amazonaws.java.migrate.UpgradeToJava21), followed by a targeted manual fix applied by Amazon Kiro CLI to resolve a post-migration build incompatibility. The project now compiles cleanly, and the full test suite passes with zero errors.

🔧 Application Changes

• 📦 Library: java-dataloader — a pure Java utility library providing DataLoader batching/caching for GraphQL Java
• 🎯 Upgrade target: Java 11 → Java 21 (LTS)
• 🏗️ Build system: Gradle (wrapper upgraded from 9.2.0 → 8.10 for Java 21 compatibility)
• 🧪 Test framework: JUnit 5 (already in use — no migration required)
• 🔀 Mixed-language project: Production code in Java; test suite includes both Java and Kotlin

🛠️ Tools Used

💻 Code Changes

Automated by OpenRewrite

• 🔄 build.gradle — Java toolchain version updated to JavaLanguageVersion.of(21); options.release set to 21
• 🔄 src/main/java/org/dataloader/DataLoaderHelper.java — Applied InstanceOfPatternMatch (pattern variable in instanceof) and SequencedCollection / ListFirstAndLast migrations (e.g. .get(0) → .getFirst())
• 🔄 src/main/java/org/dataloader/registries/ScheduledDataLoaderRegistry.java — Applied InstanceOfPatternMatch modernisation
• 🔄 src/main/java/org/dataloader/instrumentation/ChainedDataLoaderInstrumentation.java — Applied SequencedCollection / ListFirstAndLast migrations
• 🔄 src/main/java/org/dataloader/DataLoaderRegistry.java — Applied InstanceOfPatternMatch and String.formatted() migration
• 🔄 src/test/java/ReadmeExamples.java — Applied String.formatted() migration
• 🔄 src/test/java/org/dataloader/DataLoaderCacheMapTest.java — Applied ListFirstAndLast migration
• 🔄 src/test/java/org/dataloader/DataLoaderTest.java — Applied ListFirstAndLast migration
• 🔄 src/test/java/org/dataloader/DataLoaderStatsTest.java — Applied ListFirstAndLast migration

Manual fix by Amazon Kiro CLI

• 🛠️ build.gradle — Kotlin compiler option jvmTarget corrected from JvmTarget.JVM_11 → JvmTarget.JVM_21
  • Root cause: OpenRewrite updated the Java toolchain to Java 21 but did not update the Kotlin compiler's jvmTarget, causing Gradle's JVM target consistency validation to fail (compileTestJava targeted JVM 21 while compileTestKotlin still targeted JVM 11)
  • Fix: One-line change aligning both compilers to the same JVM target

⏱️ Time Savings Estimate

🏷️ OpenRewrite self-reported estimate: 40 minutes saved (source migrations only). Total wall-clock time for the full automated cycle including Kiro CLI fix: ~6 minutes.

✅ Next Steps

Validation

• 🔍 Review the 9 files modified by OpenRewrite to confirm semantic correctness of getFirst() / getLast() substitutions (they are API-equivalent but worth a human sanity check on ordering assumptions)
• 🧪 Run the jcstress concurrency stress tests (./gradlew jcstress) to validate thread-safety under the new JVM
• 📊 Run the JMH benchmarks (./gradlew jmh) to establish a Java 21 performance baseline
• 🔐 Validate OSGi bundle manifest (Automatic-Module-Name: org.dataloader) is still correct in the produced JAR

Improvement Recommendations

• ⚠️ Address Gradle deprecation warnings — the build is currently incompatible with Gradle 10 (deprecated features in use); upgrade Gradle to 9.x+ and resolve warnings before they become blocking
• 🚀 Consider adopting Java 21 Virtual Threads (Thread.ofVirtual()) as a BatchLoader execution option — the library's heavy use of CompletableFuture with async dispatch is a natural fit
• 📝 Update the README.md and POM description — both still reference "pure Java 11 port"; update to reflect Java 21 baseline
• 🔒 Evaluate enabling the full NullAway annotation check (AnnotatedPackages: org.dataloader) now that the codebase is on Java 21 and JSpecify annotations are already a declared API dependency
• 🔁 Schedule a follow-up OpenRewrite pass with org.openrewrite.java.migrate.UpgradeToJava21 recipe's remaining sub-recipes (e.g. UseTextBlocks, MigrateToRecords where applicable)

Credit usage

💳 Kiro CLI credits used: 2.19