Java Migrate

Interactive Java version upgrade guide (8 to 11, 11 to 17, 17 to 21). Use when user asks to "migrate to Java 17", "upgrade to Java 21", "Java migration guide", "move from Java 11 to 17", or "what changed in Java 21".

Guide the migration of a Java project to a newer Java version. This is an interactive migration assistant.

Step 1 — Detect current version

Check pom.xml (<java.version>, <maven.compiler.source>, <maven.compiler.target>) or build.gradle (sourceCompatibility, javaVersion). Ask for target version if not specified.

Step 2 — Build the migration checklist

Java 8 → Java 11

Breaking changes to fix:

  • Remove sun.* and com.sun.* internal API usage → find public alternatives
  • Remove JavaEE modules now removed from JDK: javax.xml.bind (JAXB), javax.activation, javax.annotation → add as Maven dependencies (jakarta.xml.bind-api, etc.)
  • Fix ClassLoader.getSystemClassLoader().getResourceAsStream() → use getClass().getResourceAsStream()
  • Flag use of finalize() → deprecated, suggest Cleaner or try-with-resources

Quick wins to adopt (optional):

  • var for local variables (Java 10+) where type is obvious
  • List.of(), Map.of(), Set.of() instead of Collections.unmodifiableList(Arrays.asList(...))
  • String new methods: isBlank(), strip(), lines(), repeat()
  • Optional.ifPresentOrElse(), Optional.or()

Build changes:

<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>

Java 11 → Java 17

Breaking changes to fix:

  • Strong encapsulation of JDK internals — fix any --add-opens flags (may need library updates)
  • Remove deprecated SecurityManager usage
  • Fix sun.misc.Unsafe direct usage → find library replacements

Quick wins to adopt (optional):

  • Records for immutable data classes (Java 16+)
  • Sealed classes for fixed hierarchies (Java 17)
  • Pattern matching instanceof (Java 16+)
  • Text blocks for multi-line strings (Java 15+)
  • Switch expressions (Java 14+)

Java 17 → Java 21

Breaking changes to fix:

  • None significant — Java 21 is largely additive

Quick wins to adopt (optional):

  • Virtual threads for I/O-bound thread pools (Java 21)
  • Sequenced collections: getFirst(), getLast() (Java 21)
  • Pattern matching switch (standard in Java 21)
  • Structured concurrency preview (Java 21)

Step 3 — Generate migration task list

Output a numbered checklist:

Migration: Java [current] → Java [target]

REQUIRED (must fix before compiling):
[ ] 1. [specific change with file/class reference if visible]
[ ] 2. ...

RECOMMENDED (adopt for better code):
[ ] 3. [specific improvement]
[ ] 4. ...

BUILD CHANGES:
[ ] Update pom.xml/build.gradle compiler version
[ ] Update CI/CD Java version
[ ] Update Docker base image (e.g., eclipse-temurin:[target]-jre)

Step 4 — Offer to scan

If the project files are accessible: "Want me to scan your codebase for the required changes above?"

Next Steps

  • After migration → run /java-review to catch any remaining issues
  • After migration → run /java-refactor to adopt new idioms
  • Update Spring Boot version if migrating to Java 17+ (Spring Boot 3.x requires Java 17+)