Java Knowledge Patch

Java Compatibility Guide

Use this skill when writing, reviewing, or migrating Java applications, build logic, launch scripts, runtime images, or operational tooling whose behavior depends on recent JDK changes.

Prefer the project's declared toolchain and the runtime actually used in production. Check build files, CI images, container bases, service definitions, IDE launchers, and native packaging before recommending a migration.

How to use this skill

1. Identify the compile JDK, runtime JDK, and whether preview features are enabled.
2. Search every launch surface for removed, deprecated, or experimental VM options.
3. Check source and bytecode for removed APIs before investigating secondary failures.
4. Rebuild preview-dependent code for the exact JDK release that will run it.
5. Rebuild AOT caches when the application or any runtime input changes.
6. Validate trust stores, providers, proxies, firewalls, and monitoring agents as deployment inputs rather than treating the source tree as the whole migration surface.
7. Open the topic reference that matches the work; do not infer old behavior from a similarly named replacement.

Reference index

Breaking-change quick reference

Treat source, bytecode, and launch configuration separately

• Source compilation can fail after removal of Applet types.
• Existing bytecode can fail to link when it reaches a removed member such as Thread.stop().
• A service can fail before application startup because the launcher rejects a removed option.
• A running application can still be incorrect because a trust root, provider algorithm, monitoring interface, or platform compatibility property changed.

High-risk removed surfaces

• Security Manager enablement is an error; legacy permission types are migration-only surfaces and are themselves removal targets.
• Non-generational ZGC is gone. Configure ZGC without assuming the old mode remains selectable.
• java.net.Socket constructors no longer provide datagram sockets. Use DatagramSocket or DatagramChannel.
• Applet APIs and Thread.stop() are gone. Replace them at source and account for linkage errors from old bytecode.
• jrunscript is gone after first being deprecated for removal.
• The bundled experimental Graal JIT and 32-bit x86 JDK ports are not portable migration assumptions.

Launcher and VM option audit

Search service units, shell scripts, container commands, build plugins, test harnesses, and IDE metadata for:

• Removed launcher options: -t, -tm, -Xfuture, -checksource, -cs, and -noasyncgc.
• Removal-target aliases: -verbosegc, -noclassgc, -verify, -verifyremote, -ss, -ms, and -mx.
• Removal-target tuning options: Xmaxjitcodesize, AlwaysActAsServerClassMachine, NeverActAsServerClassMachine, AggressiveHeap, and MaxRAM.
• Explicit UseCompressedClassPointers tuning. The underlying feature remains; the explicit option is the compatibility risk.

Move logging to unified logging and use supported long-form VM options.

Deprecation quick reference

Plan removal work for these categories before they become startup or linkage failures:

• ZipError, old Security Manager permission classes, and XML interchange in JMX DescriptorSupport.
• jstatd, jhsdb debugd, and the already removed jrunscript.
• jdk.jsobject and legacy HotSpot locking modes.
• Linux VFORK, java.locale.useOldISOCodes, and explicit compressed-class- pointer tuning.
• 32-bit Linux x86 distributions and native artifacts.

Do not interpret deprecation of an option as removal of the feature it used to tune. Verify the documented replacement or VM-selected behavior.

Preview and language quick reference

Preview discipline

• Compile and run preview code with --enable-preview.
• Recompile preview-dependent code for every JDK release.
• Remove preview enablement only when no remaining source or dependency needs it.
• Update source when a preview evolves; recompilation alone may not be enough.
• Keep module flags for incubating APIs such as the Vector API.

Module imports

A module import does not import subpackages and does not 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; its reach follows java.se's transitive requirements.

Compact source files

IO is in java.lang, but its static methods are not implicitly imported. Call IO.println(...) or add an explicit static import. Its I/O is backed by System.in and System.out, not java.io.Console.

API status checks

• Class-file parsing, generation, and transformation are available through the final Class-File API.
• Stream gatherers are final for custom intermediate stream operations.
• Module imports, compact source files and instance main methods, flexible constructor bodies, scoped values, and KDF are permanent features.
• Primitive patterns, structured concurrency, lazy constants, and PEM encodings require release-specific preview checks.

Runtime quick reference

Garbage collection and object layout

• Generational ZGC is the only ZGC mode.
• Generational Shenandoah and compact object headers moved from experimental to product status; do not retain the experimental unlock solely for them.
• Compact object headers use 64-bit headers on supported 64-bit platforms.
• AOT object caches are collector-neutral, but their other application and runtime compatibility constraints still apply.

AOT cache safety

Treat an AOT cache as derived deployment output. Rebuild it when the application, class path, module path, or JDK changes. A cache may reuse method profiles, but it remains coupled to the inputs used to create it.

Threads and diagnostics

Most virtual threads blocked in synchronized code can unmount from carrier threads, so do not diagnose every synchronized block as carrier pinning.

JFR CPU-time profiling, cooperative stack sampling, and method timing or tracing are experimental diagnostics. Method tracing instruments code; scope it narrowly.

Security and networking quick reference

• Treat native-access and sun.misc.Unsafe warnings as migration work, not harmless noise.
• Validate ML-KEM, ML-DSA, KDF, and PEM needs against API status for the selected toolchain.
• Audit trust chains after default-root removals; do not assume a certificate remains trusted because an older JDK trusted it.
• Audit provider algorithms when relying on SunPKCS11 PBE factories or older DESede and PKCS1Padding requirements.
• For HTTP/3, test QUIC over UDP through network policy, proxies, firewalls, fallback paths, certificate handling, and observability.
• Do not attempt to restore JNDI remote code downloading; it is permanently disabled.

Symptom-driven lookup

Review checklist

• Confirm compile and runtime JDKs.
• Identify every preview and incubator dependency.
• Scan all launcher surfaces, not only the main build file.
• Search source and packaged bytecode for removed APIs.
• Review GC, object-header, and AOT settings together.
• Review native access and final-field mutation grants for minimum scope.
• Validate trust roots and provider algorithms in a production-like image.
• Exercise HTTP/3 fallback and UDP network policy where applicable.
• Replace unsupported monitoring inputs with JFR, JMX, or supported serviceability APIs.
• Record which caches, images, native artifacts, and installers must be rebuilt.