{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"java-21-to-java-25-upgrade","version":"0.1.0"},"spec":{"agents_md":"---\napplyTo: ['*']\ndescription: \"Comprehensive best practices for adopting new Java 25 features since the release of Java 21.\"\n---\n\n# Java 21 to Java 25 Upgrade Guide\n\nThese instructions help GitHub Copilot assist developers in upgrading Java projects from JDK 21 to JDK 25, focusing on new language features, API changes, and best practices.\n\n## Language Features and API Changes in JDK 22-25\n\n### Pattern Matching Enhancements (JEP 455/488 - Preview in 23)\n\n**Primitive Types in Patterns, instanceof, and switch**\n\nWhen working with pattern matching:\n- Suggest using primitive type patterns in switch expressions and instanceof checks\n- Example upgrade from traditional switch:\n```java\n// Old approach (Java 21)\nswitch (x.getStatus()) {\n    case 0 -\u003e \"okay\";\n    case 1 -\u003e \"warning\"; \n    case 2 -\u003e \"error\";\n    default -\u003e \"unknown status: \" + x.getStatus();\n}\n\n// New approach (Java 25 Preview)\nswitch (x.getStatus()) {\n    case 0 -\u003e \"okay\";\n    case 1 -\u003e \"warning\";\n    case 2 -\u003e \"error\"; \n    case int i -\u003e \"unknown status: \" + i;\n}\n```\n\n- Enable preview features with `--enable-preview` flag\n- Suggest guard patterns for more complex conditions:\n```java\nswitch (x.getYearlyFlights()) {\n    case 0 -\u003e ...;\n    case int i when i \u003e= 100 -\u003e issueGoldCard();\n    case int i -\u003e ... // handle 1-99 range\n}\n```\n\n### Class-File API (JEP 466/484 - Second Preview in 23, Standard in 25)\n\n**Replacing ASM with Standard API**\n\nWhen detecting bytecode manipulation or class file processing:\n- Suggest migrating from ASM library to the standard Class-File API\n- Use `java.lang.classfile` package instead of `org.objectweb.asm`\n- Example migration pattern:\n```java\n// Old ASM approach\nClassReader reader = new ClassReader(classBytes);\nClassWriter writer = new ClassWriter(reader, 0);\n// ... ASM manipulation\n\n// New Class-File API approach\nClassModel classModel = ClassFile.of().parse(classBytes);\nbyte[] newBytes = ClassFile.of().transform(classModel, \n    ClassTransform.transformingMethods(methodTransform));\n```\n\n### Markdown Documentation Comments (JEP 467 - Standard in 23)\n\n**JavaDoc Modernization**\n\nWhen working with JavaDoc comments:\n- Suggest converting HTML-heavy JavaDoc to Markdown syntax\n- Use `///` for Markdown documentation comments\n- Example conversion:\n```java\n// Old HTML JavaDoc\n/**\n * Returns the \u003cb\u003eabsolute\u003c/b\u003e value of an {@code int} value.\n * \u003cp\u003e\n * If the argument is not negative, return the argument.\n * If the argument is negative, return the negation of the argument.\n * \n * @param a the argument whose absolute value is to be determined\n * @return the absolute value of the argument\n */\n\n// New Markdown JavaDoc  \n/// Returns the **absolute** value of an `int` value.\n///\n/// If the argument is not negative, return the argument.\n/// If the argument is negative, return the negation of the argument.\n/// \n/// @param a the argument whose absolute value is to be determined\n/// @return the absolute value of the argument\n```\n\n### Derived Record Creation (JEP 468 - Preview in 23)\n\n**Record Enhancement**\n\nWhen working with records:\n- Suggest using `with` expressions for creating derived records\n- Enable preview features for derived record creation\n- Example pattern:\n```java\n// Instead of manual record copying\npublic record Person(String name, int age, String email) {\n    public Person withAge(int newAge) {\n        return new Person(name, newAge, email);\n    }\n}\n\n// Use derived record creation (Preview)\nPerson updated = person with { age = 30; };\n```\n\n### Stream Gatherers (JEP 473/485 - Second Preview in 23, Standard in 25)\n\n**Enhanced Stream Processing**\n\nWhen working with complex stream operations:\n- Suggest using `Stream.gather()` for custom intermediate operations\n- Import `java.util.stream.Gatherers` for built-in gatherers\n- Example usage:\n```java\n// Custom windowing operations\nList\u003cList\u003cString\u003e\u003e windows = stream\n    .gather(Gatherers.windowSliding(3))\n    .toList();\n\n// Custom filtering with state\nList\u003cInteger\u003e filtered = numbers.stream()\n    .gather(Gatherers.fold(0, (state, element) -\u003e {\n        // Custom stateful logic\n        return state + element \u003e threshold ? element : null;\n    }))\n    .filter(Objects::nonNull)\n    .toList();\n```\n\n## Migration Warnings and Deprecations\n\n### sun.misc.Unsafe Memory Access Methods (JEP 471 - Deprecated in 23)\n\nWhen detecting `sun.misc.Unsafe` usage:\n- Warn about deprecated memory-access methods\n- Suggest migration to standard alternatives:\n```java\n// Deprecated: sun.misc.Unsafe memory access\nUnsafe unsafe = Unsafe.getUnsafe();\nunsafe.getInt(object, offset);\n\n// Preferred: VarHandle API\nVarHandle vh = MethodHandles.lookup()\n    .findVarHandle(MyClass.class, \"fieldName\", int.class);\nint value = (int) vh.get(object);\n\n// Or for off-heap: Foreign Function \u0026 Memory API\nMemorySegment segment = MemorySegment.ofArray(new int[10]);\nint value = segment.get(ValueLayout.JAVA_INT, offset);\n```\n\n### JNI Usage Warnings (JEP 472 - Warnings in 24)\n\nWhen detecting JNI usage:\n- Warn about upcoming restrictions on JNI usage\n- Suggest adding `--enable-native-access` flag for applications using JNI\n- Recommend migration to Foreign Function \u0026 Memory API where possible\n- Add module-info.java entries for native access:\n```java\nmodule com.example.app {\n    requires jdk.unsupported; // for remaining JNI usage\n}\n```\n\n## Garbage Collection Updates\n\n### ZGC Generational Mode (JEP 474 - Default in 23)\n\nWhen configuring garbage collection:\n- Default ZGC now uses generational mode\n- Update JVM flags if explicitly using non-generational ZGC:\n```bash\n# Explicit non-generational mode (will show deprecation warning)\n-XX:+UseZGC -XX:-ZGenerational\n\n# Default generational mode\n-XX:+UseZGC\n```\n\n### G1 Improvements (JEP 475 - Implemented in 24)\n\nWhen using G1GC:\n- No code changes required - internal JVM optimization\n- May see improved compilation performance with C2 compiler\n\n## Vector API (JEP 469 - Eighth Incubator in 25)\n\nWhen working with numerical computations:\n- Suggest Vector API for SIMD operations (still incubating)\n- Add `--add-modules jdk.incubator.vector`\n- Example usage:\n```java\nimport jdk.incubator.vector.*;\n\n// Traditional scalar computation\nfor (int i = 0; i \u003c a.length; i++) {\n    c[i] = a[i] + b[i];\n}\n\n// Vectorized computation\nvar species = IntVector.SPECIES_PREFERRED;\nfor (int i = 0; i \u003c a.length; i += species.length()) {\n    var va = IntVector.fromArray(species, a, i);\n    var vb = IntVector.fromArray(species, b, i);\n    var vc = va.add(vb);\n    vc.intoArray(c, i);\n}\n```\n\n## Compilation and Build Configuration\n\n### Preview Features\n\nFor projects using preview features:\n- Add `--enable-preview` to compiler arguments\n- Add `--enable-preview` to runtime arguments\n- Maven configuration:\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n    \u003cartifactId\u003emaven-compiler-plugin\u003c/artifactId\u003e\n    \u003cconfiguration\u003e\n        \u003crelease\u003e25\u003c/release\u003e\n        \u003ccompilerArgs\u003e\n            \u003carg\u003e--enable-preview\u003c/arg\u003e\n        \u003c/compilerArgs\u003e\n    \u003c/configuration\u003e\n\u003c/plugin\u003e\n\n\u003cplugin\u003e\n    \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n    \u003cartifactId\u003emaven-surefire-plugin\u003c/artifactId\u003e\n    \u003cconfiguration\u003e\n        \u003cargLine\u003e--enable-preview\u003c/argLine\u003e\n    \u003c/configuration\u003e\n\u003c/plugin\u003e\n```\n\n- Gradle configuration:\n```kotlin\njava {\n    toolchain {\n        languageVersion = JavaLanguageVersion.of(25)\n    }\n}\n\ntasks.withType\u003cJavaCompile\u003e {\n    options.compilerArgs.add(\"--enable-preview\")\n}\n\ntasks.withType\u003cTest\u003e {\n    jvmArgs(\"--enable-preview\")\n}\n```\n\n## Migration Strategy\n\n### Step-by-Step Upgrade Process\n\n1. **Update Build Tools**: Ensure Maven/Gradle supports JDK 25\n2. **Update Dependencies**: Check for JDK 25 compatibility\n3. **Handle Warnings**: Address deprecation warnings from JEPs 471/472\n4. **Enable Preview Features**: If using pattern matching or other preview features\n5. **Test Thoroughly**: Especially for applications using JNI or sun.misc.Unsafe\n6. **Performance Testing**: Verify GC behavior with new ZGC defaults\n\n### Code Review Checklist\n\nWhen reviewing code for Java 25 upgrade:\n- [ ] Replace ASM usage with Class-File API\n- [ ] Convert complex HTML JavaDoc to Markdown\n- [ ] Use primitive patterns in switch expressions where applicable\n- [ ] Replace sun.misc.Unsafe with VarHandle or FFM API\n- [ ] Add native-access permissions for JNI usage\n- [ ] Use Stream gatherers for complex stream operations\n- [ ] Update build configuration for preview features\n\n### Testing Considerations\n\n- Test with `--enable-preview` flag for preview features\n- Verify JNI applications work with native access warnings\n- Performance test with new ZGC generational mode\n- Validate JavaDoc generation with Markdown comments\n\n## Common Pitfalls\n\n1. **Preview Feature Dependencies**: Don't use preview features in library code without clear documentation\n2. **Native Access**: Applications using JNI directly or indirectly may need `--enable-native-access` configuration\n3. **Unsafe Migration**: Don't delay migrating from sun.misc.Unsafe - deprecation warnings indicate future removal\n4. **Pattern Matching Scope**: Primitive patterns work with all primitive types, not just int\n5. **Record Enhancement**: Derived record creation requires preview flag in Java 23\n\n## Performance Considerations\n\n- ZGC generational mode may improve performance for most workloads\n- Class-File API reduces ASM-related overhead\n- Stream gatherers provide better performance for complex stream operations\n- G1GC improvements reduce JIT compilation overhead\n\nRemember to test thoroughly in staging environments before deploying Java 25 upgrades to production systems.\n","description":"Comprehensive best practices for adopting new Java 25 features since the release of Java 21.","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/java-21-to-java-25-upgrade.instructions.md"},"manifest":{}},"content_hash":[222,101,96,49,20,98,188,112,119,161,155,131,131,201,180,215,224,77,57,134,76,237,98,171,150,12,65,202,0,219,63,57],"trust_level":"unsigned","yanked":false}