migrate-jdk25

Description

Automated toolkit for migrating Java projects from JDK8 to JDK25 with Spring Boot 3.x upgrade, enabling ZGC, virtual threads, and reactive programming best practices.

This skill provides comprehensive migration assistance including:

• Dependency upgrades (Spring Boot 3.5.5, Dubbo 3.3.4, etc.)
• JVM configuration for ZGC and virtual threads
• javax to jakarta namespace migration
• Spring Boot 3.x configuration updates
• Common issue detection and resolution
• Reactive programming pattern transformation

When to Use

Use this skill when:

• Migrating existing Java projects from JDK8/11/17 to JDK25
• Upgrading Spring Boot 2.x to Spring Boot 3.x
• Enabling ZGC garbage collector and virtual threads
• Converting traditional blocking code to reactive patterns
• Troubleshooting JDK25 migration issues

Prerequisites

• Python 3.10+ with uv package manager installed
• Git repository (for tracking changes)
• Target project uses Maven for build management
• Backup your project before running migration scripts

Features

1. Automated Dependency Upgrade

Upgrades Maven dependencies in pom.xml:

• Spring Boot → 3.5.5
• Spring Framework → 6.2.11
• Dubbo → 3.3.4-mone-v2-SNAPSHOT
• Lombok → 1.18.40
• Nacos → 2.1.2-XIAOMI
• commons-pool2 → 2.12.0
• mapstruct → 1.5.3.Final

2. Namespace Migration (javax → jakarta)

Automatically converts:

• javax.validation.* → jakarta.validation.*
• javax.annotation.* → jakarta.annotation.*
• javax.persistence.* → jakarta.persistence.*
• And more...

3. Spring Boot 3.x Configuration Migration

• Migrates META-INF/spring.factories to AutoConfiguration.imports
• Updates application properties for circular dependency support
• Fixes @Bean method signatures (void detection)
• Updates setter method visibility for @Value annotations

4. JVM Configuration Generator

Generates optimized JVM parameters for:

• ZGC garbage collector
• Virtual thread scheduler
• Module system (--add-opens, --add-exports)
• GC logging and heap dump configuration

5. Reactive Programming Templates

Provides code templates and migration guides for:

• Converting blocking I/O to reactive Mono/Flux
• WebFlux integration
• R2DBC database access
• Reactive Redis operations
• Reactive Dubbo RPC calls

Usage

Quick Start

# Navigate to your Java project root
cd /path/to/your/project

# Run the migration wizard
uv run migrate-jdk25/migrate.py --interactive

# Or run specific migration steps
uv run migrate-jdk25/migrate.py --step dependencies
uv run migrate-jdk25/migrate.py --step namespace
uv run migrate-jdk25/migrate.py --step config

Migration Steps

1. Analyze Project

   uv run migrate-jdk25/analyze.py --project-dir .
   

   Scans your project and generates a migration report with potential issues.

2. Upgrade Dependencies

   uv run migrate-jdk25/upgrade_dependencies.py --pom pom.xml
   

   Updates Maven dependencies to JDK25-compatible versions.

3. Migrate Namespaces

   uv run migrate-jdk25/migrate_namespace.py --source-dir src/main/java
   

   Converts javax.* imports to jakarta.* across all Java files.

4. Update Configurations

   uv run migrate-jdk25/migrate_config.py --project-dir .
   

   Migrates Spring Boot configuration files and auto-configuration.

5. Generate JVM Parameters

   uv run migrate-jdk25/generate_jvm_params.py --memory 8G --threads 10000
   

   Creates JVM startup parameters for your deployment.

6. Validate Migration

   uv run migrate-jdk25/validate.py --project-dir .
   

   Checks for common migration issues and missing configurations.

Common Issues Handled

Build & Compilation

• ✅ Unsupported class file major version 69
• ✅ Lombok and MapStruct annotation processor conflicts
• ✅ Maven compiler plugin configuration

Runtime Issues

• ✅ NoClassDefFoundError for moved classes
• ✅ Spring auto-configuration not loading
• ✅ @Bean method void return type
• ✅ @Value on private setter methods
• ✅ Redis lettuce version compatibility

Dependency Conflicts

• ✅ Jedis version conflicts (4.x → 3.8.0)
• ✅ SnakeYAML version issues
• ✅ Prometheus client conflicts
• ✅ RocketMQ Spring Boot Starter compatibility

Virtual Thread Best Practices

The skill includes guidance on:

• Converting thread pools to virtual thread executors
• Avoiding synchronized pinning (fixed in JDK25)
• Configuring virtual thread scheduler parallelism
• Dubbo virtual thread configuration

Reactive Programming Guide

Comprehensive examples for:

• Mono/Flux creation and transformation
• Error handling in reactive streams
• Converting blocking code to reactive
• Database access with R2DBC
• Redis reactive templates
• Reactive Dubbo integration

Output

Migration scripts will:

• Create backup branches in Git
• Generate detailed migration logs
• Produce JVM parameter files
• Create issue tracking reports
• Suggest manual review points

Safety Features

• Automatic Git backup before changes
• Dry-run mode for preview
• Rollback capability
• Validation checks at each step
• Detailed logging for audit trail

References

Based on the official migration guide: "升级JDK25&响应式最佳实践.pdf"

Key documents:

• JDK 25 Release Notes: https://jdk.java.net/25/
• Spring Boot 3.x Migration: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide
• JEP 491: Synchronization improvements for virtual threads

Support

For issues and questions:

• Check the generated migration report
• Review common issues in the skill guide
• Consult the original PDF documentation