java-migration
Guide for upgrading Java projects between major versions (8→11→17→21→25)
Install / Use
npx skills add decebals/claude-code-java --skill java-migrationInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of java-migration
java-migration scores 89/100 on our quality scale, 1719th of 4,702 Development & Engineering skills we index (top 37%).
Its SKILL.md is 14 KB long, well organised into 57 sections with 27 code examples: a thorough specification that gives an agent plenty to work with.
It has 747 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so java-migration is actively maintained.
- Our last check on 2026-10-31 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
java-migration compared with similar skills
All 4 of these similar skills score higher than java-migration; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| java-migration (this skill)by decebals | 89 | 747 | 2mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.3k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.4k | 3d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.7k | today | MCP Server |
Frequently asked questions
- How do I install java-migration?
- Run
npx skills add decebals/claude-code-java --skill java-migration. The install tabs above show the steps for each supported agent. - Which AI agents does java-migration work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is java-migration safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is java-migration still maintained?
- The repository was last updated about 2 months ago, so java-migration is actively maintained.
Skill content
View source on GitHubname: java-migration description: Guide for upgrading Java projects between major versions (8→11→17→21→25). Use when user says "upgrade Java", "migrate to Java 25", "update Java version", or when modernizing legacy projects. license: MIT
Java Migration Skill
Step-by-step guide for upgrading Java projects between major versions.
When to Use
- User says "upgrade to Java 25" / "migrate from Java 8" / "update Java version"
- Modernizing legacy projects
- Spring Boot 2.x → 3.x → 4.x migration
- Preparing for LTS version adoption
Migration Paths
Java 8 (LTS) → Java 11 (LTS) → Java 17 (LTS) → Java 21 (LTS) → Java 25 (LTS)
│ │ │ │ │
└──────────────┴───────────────┴──────────────┴───────────────┘
Always migrate LTS → LTS
Quick Reference: What Breaks
| From → To | Major Breaking Changes |
|-----------|------------------------|
| 8 → 11 | Removed javax.xml.bind, module system, internal APIs |
| 11 → 17 | Sealed classes (preview→final), strong encapsulation |
| 17 → 21 | Pattern matching changes, finalize() deprecated for removal |
| 21 → 25 | Security Manager removed, Unsafe methods removed, 32-bit dropped |
Migration Workflow
Step 1: Assess Current State
# Check current Java version
java -version
# Check compiler target in Maven
grep -r "maven.compiler" pom.xml
# Find usage of removed APIs
grep -r "sun\." --include="*.java" src/
grep -r "javax\.xml\.bind" --include="*.java" src/
Step 2: Update Build Configuration
Maven:
<properties>
<java.version>21</java.version>
<maven.compiler.source>${java.version}</maven.compiler.source>
<maven.compiler.target>${java.version}</maven.compiler.target>
</properties>
<!-- Or with compiler plugin -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.12.1</version>
<configuration>
<release>21</release>
</configuration>
</plugin>
Gradle:
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
Step 3: Fix Compilation Errors
Run compile and fix errors iteratively:
mvn clean compile 2>&1 | head -50
Step 4: Run Tests
mvn test
Step 5: Check Runtime Warnings
# Run with illegal-access warnings
java --illegal-access=warn -jar app.jar
Java 8 → 11 Migration
Removed APIs
| Removed | Replacement |
|---------|-------------|
| javax.xml.bind (JAXB) | Add dependency: jakarta.xml.bind-api + jaxb-runtime |
| javax.activation | Add dependency: jakarta.activation-api |
| javax.annotation | Add dependency: jakarta.annotation-api |
| java.corba | No replacement (rarely used) |
| java.transaction | Add dependency: jakarta.transaction-api |
| sun.misc.Base64* | Use java.util.Base64 |
| sun.misc.Unsafe (partially) | Use VarHandle where possible |
Add Missing Dependencies (Maven)
<!-- JAXB (if needed) -->
<dependency>
<groupId>jakarta.xml.bind</groupId>
<artifactId>jakarta.xml.bind-api</artifactId>
<version>4.0.1</version>
</dependency>
<dependency>
<groupId>org.glassfish.jaxb</groupId>
<artifactId>jaxb-runtime</artifactId>
<version>4.0.4</version>
<scope>runtime</scope>
</dependency>
<!-- Annotation API -->
<dependency>
<groupId>jakarta.annotation</groupId>
<artifactId>jakarta.annotation-api</artifactId>
<version>2.1.1</version>
</dependency>
Module System Issues
If using reflection on JDK internals, add JVM flags:
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED
Maven Surefire:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>
--add-opens java.base/java.lang=ALL-UNNAMED
</argLine>
</configuration>
</plugin>
New Features to Adopt
// var (local variable type inference)
var list = new ArrayList<String>(); // instead of ArrayList<String> list = ...
// String methods
" hello ".isBlank(); // true for whitespace-only
" hello ".strip(); // better trim() (Unicode-aware)
"line1\nline2".lines(); // Stream<String>
"ha".repeat(3); // "hahaha"
// Collection factory methods (Java 9+)
List.of("a", "b", "c"); // immutable list
Set.of(1, 2, 3); // immutable set
Map.of("k1", "v1"); // immutable map
// Optional improvements
optional.ifPresentOrElse(
value -> process(value),
() -> handleEmpty()
);
// HTTP Client (replaces HttpURLConnection)
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.example.com"))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
Java 11 → 17 Migration
Breaking Changes
| Change | Impact |
|--------|--------|
| Strong encapsulation | --illegal-access no longer works, must use explicit --add-opens |
| Sealed classes (final) | If you used preview features |
| Pattern matching instanceof | Preview → final syntax change |
New Features to Adopt
// Records (immutable data classes)
public record User(String name, String email) {}
// Auto-generates: constructor, getters, equals, hashCode, toString
// Sealed classes
public sealed class Shape permits Circle, Rectangle {}
public final class Circle extends Shape {}
public final class Rectangle extends Shape {}
// Pattern matching for instanceof
if (obj instanceof String s) {
System.out.println(s.length()); // s already cast
}
// Switch expressions
String result = switch (day) {
case MONDAY, FRIDAY -> "Work";
case SATURDAY, SUNDAY -> "Rest";
default -> "Midweek";
};
// Text blocks
String json = """
{
"name": "John",
"age": 30
}
""";
// Helpful NullPointerException messages
// a.b.c.d() → tells exactly which part was null
Java 17 → 21 Migration
Breaking Changes
| Change | Impact |
|--------|--------|
| Pattern matching switch (final) | Minor syntax differences from preview |
| finalize() deprecated for removal | Replace with Cleaner or try-with-resources |
| UTF-8 by default | May affect file reading if assumed platform encoding |
New Features to Adopt
// Virtual Threads (Project Loom) - MAJOR
try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
executor.submit(() -> handleRequest());
}
// Or simply:
Thread.startVirtualThread(() -> doWork());
// Pattern matching in switch
String formatted = switch (obj) {
case Integer i -> "int: " + i;
case String s -> "string: " + s;
case null -> "null value";
default -> "unknown";
};
// Record patterns
record Point(int x, int y) {}
if (obj instanceof Point(int x, int y)) {
System.out.println(x + ", " + y);
}
// Sequenced Collections
List<String> list = new ArrayList<>();
list.addFirst("first"); // new method
list.addLast("last"); // new method
list.reversed(); // reversed view
// String templates (preview in 21)
// May need --enable-preview
// Scoped Values (preview) - replace ThreadLocal
ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();
ScopedValue.where(CURRENT_USER, user).run(() -> {
// CURRENT_USER.get() available here
});
Java 21 → 25 Migration
Breaking Changes
| Change | Impact |
|--------|--------|
| Security Manager removed | Applications relying on it need alternative security approaches |
| sun.misc.Unsafe methods removed | Use VarHandle or FFM API instead |
| 32-bit platforms dropped | No more x86-32 support |
| Record pattern variables final | Cannot reassign pattern variables in switch |
| ScopedValue.orElse(null) disallowed | Must provide non-null default |
| Dynamic agents restricted | Requires -XX:+EnableDynamicAgentLoading flag |
Check for Unsafe Usage
# Find sun.misc.Unsafe usage
grep -rn "sun\.misc\.Unsafe" --include="*.java" src/
# Find Security Manager usage
grep -rn "SecurityManager\|System\.getSecurityManager" --include="*.java" src/
New Features to Adopt
// Scoped Values (FINAL in Java 25) - replaces ThreadLocal
private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();
public void handleRequest(User user) {
ScopedValue.where(CURRENT_USER, user).run(() -> {
processRequest(); // CURRENT_USER.get() available here and in child threads
});
}
// Structured Concurrency (Preview, redesigned API in 25)
try (StructuredTaskScope.ShutdownOnFailure scope = StructuredTaskScope.open()) {
Subtask<User> userTask = scope.fork(() -> fetchUser(id));
Subtask<Orders> ordersTask = scope.fork(() -> fetchOrders(id));
scope.join();
scope.throwIfFailed();
return new Profile(userTask.get(), ordersTask.get());
}
// Stable Values (Preview) - lazy initialization made easy
private static final StableValue<ExpensiveService> SERVICE =
StableValue.of(() -> new ExpensiveService());
public void useService() {
SERVICE.get().doWork(); // Initialized on first access, cached thereafter
}
// Compact Object Headers - automatic, no code changes
// Objects now use 64-bit headers instead of 128-bit (less memory)
// Primitive Patterns in instanceof (Preview)
if (obj instanceof int i) {
System.out.println("int value: " + i);
}
// Module Import Declarations (Preview)
import module java.sql; // Import all public types from module
Performance Improvements (Automatic)
Java 25 includes several automatic performance improvements:
- Compact Object Headers: 8 bytes instead of 16 bytes per object
- String.hashCode() constant folding: Faster Map lookups with String keys
- AOT class loading: Faster startup with ahead-of-time cache
- Generational Shenandoah GC: Better throughput, lower pauses
Migration with OpenRewrite
# Automated Java 25 migration
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:LATEST \
-Drewrite.activeRecipes=org.openrewrite.java.migrate.UpgradeToJava25
Spring Boot Migration
Spring Boot 2.x → 3.x
Requirements:
- Java 17+ (mandatory)
- Jakarta EE 9+ (javax.* → jakarta.*)
Package Renames:
// Before (Spring Boot 2.x)
import javax.persistence.*;
import javax.validation.*;
import javax.servlet.*;
// After (Spring Boot 3.x)
import jakarta.persistence.*;
import jakarta.validation.*;
import jakarta.servlet.*;
Find & Replace:
# Find all javax imports that need migration
grep -r "import javax\." --include="*.java" src/ | grep -v "javax.crypto" | grep -v "javax.net"
Automated migration:
# Use OpenRewrite
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:LATEST \
-Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0
Dependency Updates (Spring Boot 3.x)
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.2.2</version>
</parent>
<!-- Hibernate 6 (auto-included) -->
<!-- Spring Security 6 (auto-included) -->
Hibernate 5 → 6 Changes
// ID generation strategy changed
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY) // preferred
private Long id;
// Query changes
// Before: createQuery returns raw type
// After: createQuery requires type parameter
// Before
Query query = session.createQuery("from User");
// After
TypedQuery<User> query = session.createQuery("from User", User.class);
Common Migration Issues
Issue: Reflection Access Denied
Symptom:
jav
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.3kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.4kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.7k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
