Java Evolved — Code Upgrade Skill

Modernize Java code by identifying legacy patterns and suggesting modern replacements with before/after examples sourced from 113 patterns across 11 categories (Java 7 through Java 25).

Procedures

Step 1: Determine Upgrade Scope

1. Identify the target JDK version for the project. Check pom.xml, build.gradle, or .java-version for the configured source/target level. If unspecified, ask the user.
2. Identify which categories are relevant to the task:
   • language — var, records, sealed classes, pattern matching, switch expressions, text blocks
   • collections — immutable factories, sequenced collections, unmodifiable collectors
   • strings — isBlank, strip, repeat, lines, formatted, text blocks
   • streams — toList, mapMulti, gatherers, takeWhile/dropWhile, optional improvements
   • concurrency — virtual threads, structured concurrency, scoped values, stable values
   • io — HTTP client, Files API, Path.of, transferTo, memory-mapped files
   • errors — helpful NPE, multi-catch, optional chaining, null-in-switch
   • datetime — java.time API, Duration/Period, HexFormat, Math.clamp
   • security — PEM encoding, KDF, strong random, TLS defaults
   • tooling — JShell, single-file execution, JFR, AOT preloading
   • enterprise — EJB to CDI, Servlet to JAX-RS, JDBC to JPA/jOOQ, SOAP to REST, Spring modernization
3. If performing a full codebase scan, proceed to Step 2. If upgrading specific code, skip to Step 3.

Step 2: Scan for Legacy Patterns

1. Read references/detection-patterns.md to load the detection signature database.
2. For each relevant category, search the codebase for the detection signatures listed:
   • Use grep/search for the specific code patterns documented (e.g., Collections.unmodifiableList, new Thread(, .trim().isEmpty())
   • Track each match with file path, line number, and matched pattern slug.
3. Execute python3 scripts/find-pattern.py --data-dir references/ --category {cat} --max-jdk {target} --format full to retrieve the complete before/after transformation for each detected pattern.
4. Group findings by priority:
   • Quick wins: beginner difficulty, drop-in replacements (e.g., var, List.of(), String.isBlank())
   • Moderate: intermediate difficulty, may require testing (e.g., records, sealed classes, virtual threads)
   • Significant: advanced difficulty, architectural changes (e.g., structured concurrency, enterprise migrations)
5. Format results using assets/upgrade-report-template.md.

Step 3: Upgrade Specific Code

1. Identify which legacy pattern the code uses. If unsure, read references/detection-patterns.md and match against the code.
2. Look up the specific pattern by executing: python3 scripts/find-pattern.py --data-dir references/ --keyword "{pattern_name}" --format full
3. Read the relevant category reference file from references/{category}.md for the complete transformation including:
   • Before/after code examples
   • Explanation of why the modern approach is better
   • JDK version requirements
   • Related patterns to consider alongside
4. Apply the transformation following the modern code example. Adapt to the specific codebase context — do not blindly copy-paste.
5. Check for related patterns that often co-occur. The reference files list related patterns for each entry.

Step 4: Enterprise Migration Path

If the codebase involves Java EE or early Jakarta EE, read references/enterprise.md for the complete migration mappings:

• EJB to CDI beans
• Servlet to JAX-RS endpoints
• JSF managed beans to CDI named beans
• JNDI lookups to CDI injection
• JPA EntityManager to Jakarta Data repositories
• SOAP web services to Jakarta REST
• Message-driven beans to reactive messaging
• Manual transactions to declarative @Transactional
• Spring XML configuration to annotation-driven
• Spring null safety to JSpecify

Step 5: Validate Upgrades

1. Verify the target JDK version supports all applied patterns. Each pattern specifies its minimum JDK version.
2. Ensure no pattern requires a JDK version higher than the project target.
3. Run the project's existing test suite to confirm no regressions.
4. For patterns marked as preview features, verify the project enables preview: --enable-preview.

Quick Reference by JDK Version

Error Handling

• If scripts/find-pattern.py fails with a file-not-found error, verify the --data-dir points to the references/ directory containing the category markdown files.
• If a pattern requires a JDK version higher than the project target, flag it as "future upgrade" rather than applying it.
• If the YAML data files are missing, the reference markdown files in references/ contain all pattern data and can be used directly without the script.
• If a detection signature matches but the code context differs from the pattern (e.g., intentional use of old API), skip the suggestion and note why.