Agent Skills: Java Knowledge Patch

Java Knowledge Patch

Use this skill when upgrading a JDK, reviewing Java launch configuration, adopting recently finalized or preview APIs, or diagnosing runtime behavior that changed across current JDK releases.

Working method

1. Identify the exact JDK used to compile, test, package, and run the application; these can differ in CI and production.
2. Audit launch arguments, service definitions, container entrypoints, IDE settings, build plugins, and native-image or custom-runtime pipelines.
3. Separate permanent APIs from preview, incubating, and experimental features. Apply the flags required by the selected JDK, then recompile.
4. Check removed APIs and tools before debugging secondary linkage, startup, monitoring, certificate, or provider failures.
5. Validate runtime and security changes under the deployment's real class path, module path, collector, trust store, network policy, and native libraries.

Reference index

| Reference | Topics | | --- | --- | | Migration, removals, and deprecations | Removed APIs, tools, launcher flags, VM options, platform support, and migration checks | | Language, APIs, and concurrency | Module imports, preview discipline, finalized APIs, compact source files, stable values, and HTTP/3 | | Runtime, GC, AOT, and diagnostics | Collector changes, object headers, virtual threads, AOT caches, JFR, and runtime images | | Security and cryptography | Security Manager, native access, final fields, KDF, ML-KEM, ML-DSA, PEM, trust roots, and providers |

Breaking changes: start here

Removed launcher and VM surfaces

• Remove -t, -tm, -Xfuture, -checksource, -cs, and -noasyncgc; the java launcher no longer accepts them.
• Replace old aliases such as -verbosegc, -noclassgc, -verify, -verifyremote, -ss, -ms, and -mx with current long-form VM options or unified logging.
• Remove tuning assumptions around Xmaxjitcodesize, AlwaysActAsServerClassMachine, NeverActAsServerClassMachine, AggressiveHeap, and MaxRAM; they are removal targets.

Removed APIs and tools

• The Applet APIs and javax.swing.JApplet are gone. Old bytecode can fail to link as well as old source failing to compile.
• Thread.stop() is gone; use interruption or another cooperative cancellation protocol. Existing bytecode may throw NoSuchMethodError.
• jrunscript is gone, and jstatd, jdk.jsobject, ZipError, legacy locking modes, and jhsdb debugd are on a removal path.
• java.net.Socket constructors cannot create datagram sockets. Use DatagramSocket or DatagramChannel.

Disabled and restricted behavior

• Enabling the Security Manager is an error. Treat its remaining APIs only as temporary migration aids.
• JNI and restricted Foreign Function and Memory use warn without an explicit native-access grant. Resolve the warnings before enforcement becomes deny-by-default.
• Deep-reflection writes to final fields warn. Grant mutation narrowly with --enable-final-field-mutation, control violations with --illegal-final-field-mutation, and migrate frameworks toward supported construction or serialization.

Platform and observability removals

• Do not assume a 32-bit x86 JDK. The Windows port was removed first; the remaining x86 port and the bundled experimental Graal JIT were subsequently removed.
• Old JMX system properties, PerfData sampling, and private sun.rt._sync* counters are gone. Move agents to supported JFR, JMX, or serviceability APIs.
• Linux GTK 2 support, legacy short-zone-ID interpretation, JNDI compatibility hooks, remote code downloading, and old JMX serialization compatibility have been removed.

See Migration, removals, and deprecations for exact names and a systematic audit checklist.

Preview and finalization rules

• Compile and run preview-dependent code with --enable-preview; preview class files must be recompiled for each JDK release.
• Module imports, compact source files and instance main methods, flexible constructor bodies, scoped values, and the KDF API are permanent. Remove preview flags only when no remaining preview feature requires them.
• Primitive patterns, structured concurrency, lazy constants, and PEM encodings still use preview forms; the Vector API remains incubating.
• The Class-File API and Stream Gatherers are final and need no preview flag.

Module imports

Module imports do not import subpackages or change module readability. A type-import-on-demand declaration wins over a module import when both expose the same simple name. Do not generalize the broad reach of import module java.se; to arbitrary modules.

Compact source files

IO is in java.lang, but its static methods are not implicitly imported. Qualify calls such as IO.println(...) or add an explicit static import. Its streams are System.in and System.out, not java.io.Console.

See Language, APIs, and concurrency for code examples, feature states, and migration details.

Runtime quick reference

Garbage collectors and headers

• ZGC is generational-only; configurations selecting non-generational ZGC must be revised.
• Generational Shenandoah and compact object headers progressed from experimental modes to product features. Current startup configuration does not need -XX:+UnlockExperimentalVMOptions solely for either feature.
• When testing the earlier experimental compact-header form, unlock experimental options and enable UseCompactObjectHeaders explicitly.

Virtual threads

Virtual threads blocked in most synchronized constructs can unmount from their carrier. Reassess workarounds built around the former common pinning behavior, while still measuring the application's actual blocking paths.

AOT caches

• A training run can record loaded and linked classes for a later startup cache; the workflow also supports reuse of method profiles.
• A cache is coupled to its application and runtime inputs. Rebuild it when the application, class path, module path, or JDK changes.
• Cached objects can be stored in a collector-neutral representation, so the object cache is no longer tied to one garbage collector.

Diagnostics

Experimental JFR facilities include Linux CPU-time profiling, cooperative stack sampling, and method timing and tracing. Method tracing instruments code, so restrict it to the methods needed for the diagnostic session.

See Runtime, GC, AOT, and diagnostics for configuration and deployment implications.

Security and cryptography quick reference

• Standard facilities cover KDFs, ML-KEM key encapsulation, ML-DSA signatures, and PEM encoding/decoding of keys, certificates, and revocation lists. Check whether the selected API form is permanent or preview.
• Do not assume old roots remain in the default trust store. Test real certificate chains after a JDK update.
• Do not infer provider support from older platform requirements. Audit SunPKCS11 PBE assumptions and verify PBES2 capabilities explicitly.
• Treat the first warning from terminally deprecated sun.misc.Unsafe memory-access methods as a dependency migration signal.

See Security and cryptography for the specific root and provider changes and the native/reflection migration knobs.

Upgrade verification checklist

• Search every launch surface for removed and deprecated flags.
• Compile without stale preview flags, then add back only those required by features that remain preview.
• Run linkage tests for removed Applet and thread-stopping APIs.
• Exercise custom runtime images, native libraries, agents, and monitoring integrations.
• Recreate AOT caches using the deployed application and runtime inputs.
• Test collectors, compact headers, and virtual-thread workloads under load.
• Validate QUIC over UDP, proxy and firewall behavior, HTTP fallback, certificates, and telemetry before enabling HTTP/3.
• Validate trust chains and cryptographic provider algorithms in the target runtime rather than relying on prior defaults.