Jvm Helper

JVM Helper

Use the project's wrappers and toolchains, distinguish stable APIs from previews, and measure runtime behavior before changing JVM flags. Current releases are not automatic migration targets for an existing project.

Current baseline

Verified 2026-08-03:

Spring Boot 4.1.0, Ktor 3.5.1, and Shadow 9.6.1 are current, but their major upgrades are not drop-in substitutions for an existing build.

Read references/releases.md for the 75-page research ledger. Read references/java-and-kotlin.md for current language/concurrency APIs. Read references/build-and-test.md for wrappers, Gradle, Maven, JUnit, and build-cache correctness. Read references/diagnostics-and-packaging.md for jcmd/JFR/JMX, JVM tuning, jlink, jpackage, and Native Image.

Establish the toolchain

java --version
javac --version
./gradlew --version
./mvnw --version

Prefer repository wrappers and declared Java toolchains. A globally installed current JDK does not change the project's source, target, runtime, or support contract.

Command authority

Build and test commands create outputs and can resolve dependencies:

./gradlew build
./mvnw verify

Live-process diagnostics can pause, attach to, or materially affect the target. Inspect the command's documented impact and production authority before running jcmd, jmap, heap dumps, or JFR operations. jmap is experimental and unsupported; prefer supported jcmd operations where appropriate.

Verification without skipped tests

Do not recommend -x test, -DskipTests, or maven.test.skip as a normal workflow. assemble only creates artifacts and does not satisfy verification.

For Maven, verify runs integration tests only when Failsafe or another plugin is bound to the integration-test and verify lifecycle phases. Check the POM before making the claim.

For Gradle, configure useJUnitPlatform() and the intended test suites. JUnit parallel execution is opt-in and must preserve test isolation.

Java concurrency

Virtual threads are appropriate for large numbers of blocking tasks, not CPU-bound parallelism. Create them through application-owned executors and close executor lifecycles.

JDK 24 eliminated nearly all virtual-thread pinning caused by synchronized. Do not mechanically replace correct synchronization with ReentrantLock; use JFR or jcmd to diagnose remaining pinning cases.

Structured Concurrency remains preview. The API changed across previews. On JDK 25, use StructuredTaskScope.open() or open(Joiner...), compile with --enable-preview --release 25, and run with --enable-preview. Verify the exact target JDK docs before copying an example.

Scoped Values finalized in JDK 25:

ScopedValue.where(CURRENT_USER, user).run(() -> handle(request));

Do not use removed preview-era runWhere examples.

HttpClient makes no guarantee that its default executor uses virtual threads. If blocking send should run in a virtual thread, create that ownership explicitly.

Kotlin coroutines

Preserve cooperative cancellation. A broad catch (Exception) can swallow CancellationException:

try {
    performWork()
} catch (cancellation: CancellationException) {
    throw cancellation
} catch (failure: IOException) {
    handleFailure(failure)
}

Dispatchers.IO defaults to max(64, availableProcessors) parallelism and is configurable. limitedParallelism views can exceed that nominal bound. Treat these as implementation controls, not an application concurrency budget.

Close executor-backed dispatchers:

Executors.newFixedThreadPool(4).asCoroutineDispatcher().use { dispatcher ->
    withContext(dispatcher) { performWork() }
}

K2 has been the default compiler since Kotlin 2.0. Remove obsolete -Pkotlin.experimental.tryK2=true guidance. Kotlin guard conditions were preview in 2.1 and stable in 2.2.

Nullability

Platform types cross an unchecked Java/Kotlin boundary. Use an identified annotation ecosystem and migration mode. Prefer JSpecify for new shared Java APIs where it fits; otherwise name the chosen JetBrains or Eclipse annotations rather than using unqualified @Nullable examples.