Modern Java (21+)

Write, review, and refactor Java the way the language is shaped today, not the way it was in 2014.

Targets Java 21+ with Java 25 as the current LTS (released 2025-09-16, supported to 2033; Java 26 is the current non-LTS, 2026-03-17). "Modern" here means: records and sealed interfaces instead of JavaBeans and type hierarchies, exhaustive pattern-matching switch instead of instanceof+cast ladders, virtual threads instead of hand-tuned pools, and ScopedValue instead of ThreadLocal. If you are reaching for a telescoping constructor, a getter/setter bean, or a manual ExecutorService sized to a core count, stop.

When to use / When NOT to use

Use when:

• Authoring, reviewing, or refactoring any .java file.
• Modeling a domain: record vs class, sealed hierarchy vs enum, where immutability belongs.
• Replacing instanceof+cast chains or visitor boilerplate with a pattern-matching switch.
• Concurrency that blocks on I/O at scale: migrating thread pools / reactive chains to virtual threads, fan-out with structured concurrency, ThreadLocal -> ScopedValue.
• Stream / Optional / Collector pipelines, and deciding when a plain loop beats a stream.
• Setting up or fixing a pom.xml / build.gradle(.kts) for a current JDK (toolchain, --release, preview flags, JUnit 5).

When NOT to use (delegate):

• Spring controllers, beans, starters, autoconfiguration, @Transactional -> spring-boot. This skill is the plain-JDK layer underneath; framework wiring is out of scope by topic.
• Kotlin on the JVM (Android or server) -> kotlin-android. Java and Kotlin interop but are different languages; coroutines and Kotlin null-safety belong there.
• Language-agnostic threat modeling / OWASP / authz -> secure-coding. This skill keeps only Java-specific controls (parametrized JDBC, compact-constructor validation, sane deser).
• Containerfile / CI pipeline / shipping -> deployment. This skill keeps only a jlink/jpackage note and the JDK base-image choice.
• PostgreSQL schema / index / query tuning -> postgresdb. This skill covers JDBC parametrization from the Java side only.
• Recording per-project conventions in a workspace wiki -> harness (see "Project grounding").

Records/sealed/pattern-matching design, virtual-thread concurrency, and the build surface live here — there is no separate "java-concurrency" or "java-build" skill.

Decision rules

Apply these on every Java edit:

1. Record by default for data. If a type just carries values, make it a record; it gets equals/hashCode/toString and is immutable for free. Class only when you need mutable identity or inheritance.
2. Sealed + exhaustive switch over instanceof ladders. A closed set of cases is a sealed interface; the compiler then proves your switch is total. An instanceof+cast ladder is an unchecked manual version of this.
3. Immutable and final by default. Fields final, collections wrapped/copied; mutate only where you have measured a reason. Shared mutable state is the bug you debug at 3am.
4. Optional is a return type, never a field or parameter. It signals "maybe absent" to a caller; an Optional field just adds a null-of-null. For absent collections, return empty.
5. Virtual threads for blocking I/O, platform threads for CPU work. Loom wins when threads spend their life parked on sockets/JDBC; it does nothing for a tight CPU loop.
6. One virtual thread per task. Never pool them. They are cheap (millions are fine); pooling them re-introduces the limit they exist to remove.
7. Validate in the compact constructor. A record's invariants belong in its compact constructor so an invalid instance cannot exist — not in a separate validate() you can forget.
8. Parametrize every JDBC query. PreparedStatement with ?, bind values; never concatenate user input into SQL.
9. Stream for transforms, loop for side-effects. A map/filter/collect pipeline is clear; a forEach that mutates external state is a loop wearing a costume — write the loop.
10. Treat compiler warnings as failures. Build with -Xlint:all -Werror; an ignored unchecked or deprecation warning is a deferred bug.

Data modeling

A record is the default data carrier — immutable, no setters, validated in its compact constructor.

// Good: invalid Money cannot exist; value semantics for free.
public record Money(long cents, Currency currency) {
    public Money {                                   // compact constructor
        if (cents < 0) throw new IllegalArgumentException("cents < 0: " + cents);
        Objects.requireNonNull(currency, "currency");
    }
    public Money plus(Money other) {
        if (!currency.equals(other.currency)) throw new IllegalArgumentException("currency mismatch");
        return new Money(cents + other.cents, currency);
    }
}

// Bad: telescoping constructors, mutable identity, hand-written equals you will get wrong.
public final class Money {
    private long cents; private Currency currency;
    public Money() {}
    public Money(long cents) { this.cents = cents; }
    public Money(long cents, Currency currency) { this.cents = cents; this.currency = currency; }
    public void setCents(long c) { this.cents = c; }   // now any caller can break invariants
    public long getCents() { return cents; }
    // ... 40 lines of getters/setters/equals/hashCode ...
}

A sealed interface + record cases is an algebraic data type — a closed set the compiler knows about:

public sealed interface PaymentResult permits Captured, Declined, Pending {}
public record Captured(String id, Money amount)        implements PaymentResult {}
public record Declined(String reason, int code)        implements PaymentResult {}
public record Pending(String id, Instant retryAfter)   implements PaymentResult {}

Enum vs sealed: use an enum when cases are a fixed set of constants with no per-case data (Status.ACTIVE); use a sealed interface when each case carries different fields (above). Reaching for an enum plus a parallel "payload" map means you wanted a sealed type.

Pattern matching

instanceof binds the pattern variable directly — no cast:

if (event instanceof Captured c) {       // Good: c is in scope, already typed
    ledger.record(c.id(), c.amount());
}

An exhaustive switch over a sealed type with record deconstruction and when guards replaces the whole ladder — and omit default when the sealed set is covered so adding a new case becomes a compile error you must handle:

// Good: total over the sealed type; deconstruction patterns; guard; null branch.
String describe(PaymentResult r) {
    return switch (r) {
        case Captured(var id, var amt) when amt.cents() == 0 -> "free capture " + id;
        case Captured(var id, var amt)                       -> "captured " + amt.cents() + "c " + id;
        case Declined(var reason, var code)                  -> "declined(" + code + "): " + reason;
        case Pending(var id, var __)                         -> "pending " + id;
        case null                                            -> "no result";
        // no default: compiler proves exhaustiveness; a new permits-case won't compile until handled
    };
}

// Bad: instanceof + cast ladder. No exhaustiveness check; a new case silently falls through.
String describe(PaymentResult r) {
    if (r instanceof Captured) { Captured c = (Captured) r; return "captured " + c.amount(); }
    else if (r instanceof Declined) { Declined d = (Declined) r; return "declined " + d.reason(); }
    else return "?";   // silently wrong when Pending is added
}

Java 25 adds primitive type patterns in instanceof and switch (e.g. case int i), extending exhaustiveness to primitives.

Concurrency: virtual threads

For blocking I/O, run one virtual thread per task inside a per-task executor closed with try-with-resources (the close call blocks until every submitted task finishes):

// Good: 500 blocking fetches, one virtual thread each. No pool sizing, no reactive ceremony.
List<String> fetchAll(List<URI> urls, HttpClient http) throws InterruptedException {
    try (var exec = Executors.newVirtualThreadPerTaskExecutor()) {
        var futures = urls.stream()
            .map(u -> exec.submit(() -> http.send(
                HttpRequest.newBuilder(u).build(), BodyHandlers.ofString()).body()))
            .toList();
        return futures.stream().map(f -> {
            try { return f.get(); } catch (Exception e) { throw new CompletionException(e); }
        }).toList();
    } // close() joins all tasks
}

// Bad: a fixed platform-thread pool caps you at N concurrent blocking calls and starves.
var exec = Executors.newFixedThreadPool(16);   // 484 of 500 fetches wait on a thread

JEP 491 (JDK 24) removed synchronized pinning — a virtual thread inside a synchronized block no longer pins its carrier, so legacy synchronized code is safe on Loom now. For long holds prefer ReentrantLock anyway (fairness, tryLock, interruptibility).

Structured concurrency (StructuredTaskScope) ties subtasks to a scope so one failure cancels the siblings — but it is still preview in Java 25 (JEP 505, 5th preview), so it needs --enable-preview. ScopedValue is FINAL in Java 25 (JEP 506) and is the immutable replacement for ThreadLocal when sharing context across virtual threads:

// Good: immutable, explicitly scoped, propagates into child tasks; nothing to clean up.
private static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();
ScopedValue.where(REQUEST_ID, id).run(() -> handle(req));   // REQUEST_ID.get() inside

A ThreadLocal set on the caller does not appear in the tasks you submit to an executor, and on millions of virtual threads its mutable per-thread copies leak memory — that symptom is exactly what ScopedValue fixes. Deep dive (scopes, joiners, pinning diagnosis, when platform threads still win) -> references/concurrency.md.

Streams, Optional, Collectors (essentials)

Use stream().toList() (Java 16+, immutable) for the common case; Collectors.groupingBy and teeing cover most aggregation:

Map<Currency, Long> totalByCcy = payments.stream()
    .collect(Collectors.groupingBy(Payment::currency,
             Collectors.summingLong(p -> p.amount().cents())));

Optional discipline: chain map/filter/orElseGet/orElseThrow; never .get() without a prior isPresent, never an Optional field. Do not stream when a loop is clearer — a forEach with side-effects, an early break/return, or index-coupled logic is a loop. Full Collector catalog, custom collectors, mapMulti, Gatherers (Java 24+), and parallel-stream caveats -> references/streams.md.

Builds

Pin the language level with the compiler plugin's <release>, run JUnit 5 via Surefire. Maven 4 is not yet GA (4.0.0-rc-5, Nov 2025) — use Maven 3.9.x for production:

<properties><maven.compiler.release>25</maven.compiler.release></properties>
<build><plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId>
    <version>3.13.0</version>
    <configuration><release>25</release>
      <compilerArgs><arg>-Xlint:all</arg><arg>-Werror</arg></compilerArgs></configuration>
  </plugin>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId>
    <version>3.5.2</version>
  </plugin>
</plugins></build>

Gradle 9.x (current 9.5.1, requires Java 17+ to run, prefers the configuration cache) uses a toolchain block so the build picks the right JDK regardless of the runner's default:

plugins { java }
java { toolchain { languageVersion = JavaLanguageVersion.of(25) } }
tasks.test { useJUnitPlatform() }

Full pom.xml / build.gradle.kts skeletons, multi-module, preview-flag wiring, JUnit 5 + AssertJ + Mockito, jlink/jpackage -> references/builds.md.

Errors & null

• Never return null. Return Optional<T> for a maybe-value, an empty collection for "none".
• try-with-resources for anything AutoCloseable; do not write a finally { close() } by hand.
• Chain exceptions — throw new ServiceException("loading user " + id, cause) — so the stack trace keeps the root. Swallowing (catch (Exception e) {}) destroys the evidence.
• Checked vs unchecked: checked (extends Exception) for recoverable, expected conditions the caller must handle; unchecked (extends RuntimeException) for programming bugs / invariant violations. Do not wrap everything in a checked exception "to be safe" — it just gets rethrown.

Anti-patterns / rationalizations -> STOP

Rationalization	Reality / Do instead
"I'll add setters to the record for convenience"	Then it isn't immutable. Build a new instance; validate in the compact constructor.
"instanceof+cast is fine, it's only three cases"	No exhaustiveness; case four silently falls through. Sealed + switch.
"pool the virtual threads to be safe"	Pooling re-adds the limit Loom removes. One virtual thread per task.
"ThreadLocal carries my request context"	It doesn't cross submit() and leaks on millions of vthreads. ScopedValue.
"Optional field so callers handle absence"	Optional is a return type. A field is null-of-null; use the value or a default.
"raw List is shorter than List<Payment>"	Raw types disable generics checks. Always parametrize.
"catch and ignore, it can't happen here"	Then assert it; a swallowed exception erases the bug. Log + rethrow or handle.
"fmt the id into the SQL string, it's trusted"	Trust nothing at the boundary. PreparedStatement with ?.
"wrap it in a checked exception to force handling"	Most callers just rethrow. Unchecked for bugs; checked only when recovery is real.
"new Thread(r).start() per request"	On platform threads that's a few thousand max. Virtual-thread-per-task executor.
"default branch keeps the switch safe"	A default hides the new case. Omit it on a sealed type so it won't compile.
"warnings are just noise"	unchecked/deprecation are deferred bugs. -Xlint:all -Werror.

Quick reference

Task	Idiom / command
Build + test (Maven)	./mvnw -q verify (or mvn -q verify)
Build + test (Gradle)	./gradlew check
Data carrier	record Money(long cents, Currency ccy) { Money { ... } }
Closed case set	sealed interface R permits A, B {} + record A(...) implements R {}
Exhaustive match	switch (r) { case A(var x) -> ...; case B b -> ...; } (no default)
Concurrent blocking I/O	try (var e = Executors.newVirtualThreadPerTaskExecutor()) { ... }
Context across threads	ScopedValue.where(KEY, val).run(() -> ...)
Run a single source file	java App.java (compact source + instance main, JEP 512, final in 25)
Local gate	./scripts/verify.sh (run in your project root)

Project grounding (02-DOCS + CLAUDE.md)

When this skill runs in a project with a 02-DOCS/ layer (the harness Karpathy wiki), record this project's Java decisions there and index them from the root CLAUDE.md, so the next agent inherits them instead of re-deriving.

1. Find the article 02-DOCS/wiki/stack/java.md, indexed in 02-DOCS/wiki/index.md (the Knowledge map index; root CLAUDE.md points to it).
2. If missing or stale, create/update it with the project's real choices — JDK/LTS target, Maven vs Gradle, the domain-modeling conventions (records/sealed), the concurrency model (virtual threads, structured-concurrency preview on/off), and the error/null conventions — then index it in 02-DOCS/wiki/index.md (the Knowledge map; root CLAUDE.md keeps only a short pointer to it).
3. Read it first on every use and stay consistent; when a convention changes, update the article (bump its Updated date) in the same change.

No 02-DOCS/ layer? Skip silently (optionally suggest harness). Technical conventions are recorded, not gated — never block the task on this.

See Also

Sibling skills (link only those present under skills/):

• spring-boot - the Spring framework surface (controllers, beans, autoconfiguration); this skill is the plain-JDK/language layer underneath it.
• secure-coding - threat modeling and language-agnostic authz/abuse/OWASP review (this skill keeps the Java-specific controls).
• deployment - Docker, CI, and shipping (this skill keeps only the jlink/jpackage note and base-image choice).
• postgresdb - SQL schema/index/query tuning (this skill covers JDBC parametrization from the Java side only).
• harness - the 02-DOCS/ workspace wiki where per-project Java conventions are recorded (see "Project grounding").

Local references (read when):

• references/concurrency.md - virtual-thread internals, structured concurrency, ScopedValue, pinning diagnosis, when platform threads still win.
• references/streams.md - full Collectors catalog, custom collectors, Gatherers, parallel-stream caveats, Stream-vs-loop decision table.
• references/builds.md - full pom.xml + build.gradle.kts skeletons, multi-module, preview flags, JUnit 5 + AssertJ + Mockito, jlink/jpackage, dependency hygiene.