Records & Sealed Classes

Introduction

Payment domain models in legacy Java meant POJOs with 80 lines of boilerplate — constructors, getters, equals, hashCode, toString — and stringly-typed status fields where "SETTLED" typos compile fine but fail in production. Records (Java 16+) are immutable data carriers with generated accessors and value semantics. Sealed classes (Java 17) restrict inheritance — your PaymentEvent hierarchy is exactly Authorized, Declined, or Pending, no rogue subclasses. Pattern matching for instanceof (Java 16) and switch expressions (Java 14+) with sealed types (Java 21) make exhaustive handling compiler-checked.

This lesson teaches modern Java domain modeling for banking — wire instructions as records, payment outcomes as sealed hierarchies, routing logic with switch expressions that fail compilation when you add a new event type. Staff engineers at Goldman and Stripe-style shops use these features to eliminate null-heavy POJOs and non-exhaustive switch bugs that cause reconciliation gaps.

Records + sealed + pattern matching are the Java answer to algebraic data types — without leaving the JVM ecosystem.

Business problem

Legacy POJO domain models fail regulated payment systems:

• Mutable state bugs: Setter on TransferDto modified after validation — double-submit to SWIFT gateway.
• Non-exhaustive switch: New ChargebackReceived event added — switch default silently drops events in audit pipeline.
• equals/hashCode drift: Developer adds field to PaymentId — forgets hashCode — HashMap lookup fails intermittently.
• Uncontrolled inheritance: Third party extends PaymentProcessor — overrides settle() with insecure impl.

Why this topic exists

Java needed concise immutable data and closed hierarchies — Kotlin data classes and sealed classes proved the model works at scale.

• Records: JEP 395 — nominal tuple for DTOs, events, value objects; compiler generates equals/hashCode/toString.
• Sealed classes: JEP 409 — author controls permitted subclasses; enables exhaustive pattern matching.
• Pattern matching instanceof: JEP 394 — cast and bind in one step — if (o instanceof Payment p).
• Switch expressions: JEP 361 + sealed — compiler verifies all cases covered — no fall-through bugs.

Core concepts

Four pillars of modern Java domain modeling:

• Records: record WireInstruction(String id, long amountCents, String beneficiarySwift) {} — immutable, final fields.
• Sealed classes: sealed interface PaymentResult permits Success, Failure, Pending { } — closed hierarchy.
• Pattern matching: Deconstruct in switch — case Success(var id, var amt) -> ... (Java 21 record patterns).
• Switch expressions: return switch (result) { case Success s -> ...; case Failure f -> ...; }; — expression yields value, exhaustiveness checked.

Internal architecture

Payment event model — sealed + records + switch:

sealed interface PaymentEvent permits Authorized, Declined, PendingReview {
}

record Authorized(String paymentId, long amountCents, Instant at) implements PaymentEvent {}
record Declined(String paymentId, String reasonCode) implements PaymentEvent {}
record PendingReview(String paymentId, String caseId) implements PaymentEvent {}

// Exhaustive routing — compiler error if case missing
String route(PaymentEvent event) {
    return switch (event) {
        case Authorized(var id, var amt, var at) ->
            "SETTLE queue: " + id + " amount=" + amt;
        case Declined(var id, var code) ->
            "NOTIFY merchant: " + id + " code=" + code;
        case PendingReview(var id, var caseId) ->
            "AML queue case=" + caseId;
    };
}

Record rules:
  • No setters — copy-with via wither pattern manual or rebuild
  • Can implement interfaces, add compact constructor validation
  • Not JPA entities (mutable persistence) — use for DTOs/events

Sealed rules:
  • permits clause lists all subclasses in same module/package
  • subclasses must be final, sealed, or non-sealed

Four concepts — model a payment lifecycle with compiler-enforced correctness.

1. Records

• Syntax: record Beneficiary(String iban, String name) {} — implicit final fields.
• Compact constructor: Validate IBAN checksum — if (iban.isBlank()) throw... before field assignment.
• Value semantics: Two records equal if all components equal — safe as HashMap keys for idempotency cache.
• Not for JPA entities: Use records for API DTOs, Kafka events, immutable snapshots — entities stay mutable classes.

2. Sealed Classes

• permits clause: sealed interface PaymentResult permits Success, Failure, Pending — exhaustive domain.
• Subclass modifiers: Each permitted type must be final, sealed, or non-sealed — controls further extension.
• Records as permits: record Success(String id) implements PaymentResult — common pattern.
• Module boundary: Sealed + module-info exports control who can extend — security for SPI plugins.

3. Pattern Matching

• instanceof: if (event instanceof Authorized auth) — auth in scope, no cast.
• Record patterns: case Authorized(var id, var amt, var at) — destructure in switch case label.
• Guarded patterns: case Authorized(var id, var amt, _) when amt > 1_000_000 — high-value routing (preview/stable).
• Exhaustiveness: Sealed hierarchy + switch — compiler warns on missing case when new type added.

4. Switch Expressions

• Arrow syntax: case Success s -> handle(s); — no break needed, no fall-through bugs.
• Expression form: var msg = switch (r) { ... }; — assigns value from all branches.
• yield: Block case body uses yield value; to return from switch expression.
• Domain routing: Map PaymentEvent to queue name — compiler fails build when AML adds new event type without handler.

Code walkthrough

Sealed payment events with record patterns and switch expression:

• Compact constructor: Authorized validates amountCents > 0 at construction — fail fast.
• Guarded case: when amt > 1_000_000 routes high-value payments separately.
• Record patterns: Destructure Authorized components directly in case label.
• instanceof pattern: extractAmount binds amt without explicit cast.
• Exhaustive switch: All three permitted types handled — new type breaks compile until case added.

import java.time.Instant;

sealed interface PaymentEvent permits Authorized, Declined, PendingReview {}

record Authorized(String paymentId, long amountCents, Instant authorizedAt)
    implements PaymentEvent {
    Authorized {
        if (amountCents <= 0) throw new IllegalArgumentException("amount must be positive");
    }
}

record Declined(String paymentId, String reasonCode) implements PaymentEvent {}
record PendingReview(String paymentId, String amlCaseId) implements PaymentEvent {}

class PaymentRouter {
    static String route(PaymentEvent event) {
        return switch (event) {
            case Authorized(var id, var amt, var at) when amt > 1_000_000L ->
                "HIGH_VALUE_SETTLEMENT:" + id;
            case Authorized(var id, var amt, _) ->
                "STANDARD_SETTLEMENT:" + id;
            case Declined(var id, var code) ->
                "DECLINE_NOTIFY:" + id + ":" + code;
            case PendingReview(var id, var caseId) ->
                "AML_HOLD:" + caseId;
        };
    }

    static long extractAmount(PaymentEvent event) {
        if (event instanceof Authorized(var id, var amt, var at)) {
            return amt;
        }
        return 0L;
    }

    public static void main(String[] args) {
        PaymentEvent ok = new Authorized("P-100", 50_000L, Instant.now());
        PaymentEvent big = new Authorized("P-200", 2_000_000L, Instant.now());
        PaymentEvent bad = new Declined("P-300", "INSUFFICIENT_FUNDS");

        System.out.println(route(ok));
        System.out.println(route(big));
        System.out.println(route(bad));
        System.out.println("Amount: " + extractAmount(ok));
    }
}

Production example

Spring Kafka — sealed event hierarchy for payment bus:

• Kafka deserialization: Polymorphic JSON needs type discriminator — @JsonSubTypes or custom — sealed hierarchy documents allowed types.
• Exhaustive handler: New LedgerEvent type — compiler forces new switch case before merge.
• Records for DTOs: BalanceSnapshot API response — immutable, JSON-friendly with Jackson 2.12+.
• Block switch cases: Multi-statement case with audit + metrics — arrow syntax with braces.

// Domain events — immutable records on sealed interface
public sealed interface LedgerEvent permits Posted, Reversed, Held {
}

public record Posted(String entryId, String accountId, long amountCents, Instant at)
    implements LedgerEvent {}

public record Reversed(String originalEntryId, String reason) implements LedgerEvent {}
public record Held(String entryId, String holdReason) implements LedgerEvent {}

@Service
public class LedgerEventHandler {
    public void handle(LedgerEvent event) {
        switch (event) {
            case Posted(var id, var acct, var amt, var at) -> {
                audit.log("POSTED", id, acct, amt);
                metrics.increment("ledger.posted", amt);
            }
            case Reversed(var origId, var reason) -> {
                audit.log("REVERSED", origId, reason);
                reconciliation.queue(origId);
            }
            case Held(var id, var reason) -> {
                compliance.notifyHold(id, reason);
            }
        }
    }

    // DTO layer — record for REST response
    public record BalanceSnapshot(String accountId, long balanceCents, Instant asOf) {}
}

Enterprise case study

Missing switch case chargeback incident: A card processor modeled payment notifications as string type field with switch statement and default: log-and-ignore. Product added CHARGEBACK_INITIATED event; backend team updated API docs but one reconciliation microservice's switch had no case — default branch logged at DEBUG. For 11 days, chargebacks never hit hold queue — $4.2M exposure before audit. Fix: migrated to sealed interface CardNotification permits ... ChargebackInitiated with record types; switch expression without default — compile error until handler added. Records replaced 12-field POJO with 4 lines.

• Symptom: Chargebacks in Kafka topic but not in hold DB — silent default branch.
• Root cause: Stringly-typed events + non-exhaustive switch with default.
• Fix: Sealed hierarchy + exhaustive switch; remove default that swallows unknown.
• Prevention: CI rule — no default in payment event switches; sealed permits reviewed in PR.

Performance considerations

Records and sealed types performance:

• Records vs classes: Same field layout — no performance penalty; equals/hashCode may be faster than hand-rolled broken impl.
• Switch on sealed: JVM may use tableswitch/lookupswitch — O(1) dispatch vs if-else chain; profile if hot path.
• Pattern matching: No reflection — compiler lowers to casts and field access — same as manual code.
• Allocation: Records allocate like classes — use for events/DTOs; not a pooling candidate unless profiling shows issue.
• Serialization: Jackson records support — slightly faster construction vs setter hydration on large batches.

Security considerations

Sealed types and records in security-sensitive code:

• Sealed SPI: PaymentProcessor sealed — only bank-approved implementations in permits — blocks classpath plugin attacks.
• Record validation: Compact constructor must validate — record can still hold invalid IBAN if no validation.
• Immutability: Records prevent post-validation mutation — defense against TOCTOU if reference leaked.
• Deserialization: Polymorphic deserialization of sealed types — whitelist permitted class names in JSON config.

Scalability considerations

Modeling at scale:

• Event sourcing: Records ideal immutable events — append-only ledger of Posted/Reversed records.
• Kafka schema evolution: Adding sealed permit requires new consumer deployment — plan coordinated rollout.
• DTO mapping: MapStruct generates mappers to/from records — batch API responses at high QPS.
• Non-sealed escape hatch: rare third-party extension via non-sealed — document security review requirement.

Production challenges

Real records/sealed adoption challenges:

• JPA incompatibility: Records can't be entities — teams need clear DTO vs entity split.
• Jackson polymorphism: Forgot @JsonSubTypes — all events deserialize as null or fail silently.
• Binary compatibility: Adding record component breaks serialization — version events carefully.
• Framework reflection: Older libs expect setters — records break; upgrade Spring Boot 3+ / Jackson 2.12+.
• Guarded pattern preview: when guards in switch — ensure CI uses same --enable-preview flags as prod if used.

Common mistakes

• Using records as JPA @Entity — persistence providers expect mutable beans and no-arg constructor.
• Adding sealed subclass without updating all switch expressions — compile error (good) but missed in multi-module builds if not rebuilt.
• Mutable field inside record (collection) — record is shallow immutable; expose unmodifiable copy in compact constructor.
• default case in payment event switch — swallows new types silently; prefer exhaustive sealed switch.
• Record implements Serializable without serialVersionUID plan — component add breaks compat.

Debugging guide

Debug sealed hierarchies and records:

• toString: Records auto toString — log full event in Kafka consumer without manual formatting.
• Pattern match failure: ClassCastException means non-sealed rogue type in collection — validate at deserialization.
• Switch compile errors: "pattern not exhaustive" — add case for new permitted type — intentional safety net.
• Equals surprises: Record with array field — arrays compared by reference; use List in record instead.
• Jackson: Enable FAIL_ON_UNKNOWN_PROPERTIES — catch schema drift early.

# Jackson polymorphic sealed deserialization
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = Authorized.class, name = "authorized"),
    @JsonSubTypes.Type(value = Declined.class, name = "declined")
})
public sealed interface PaymentEvent permits Authorized, Declined {}

# Log record in consumer
log.info("Event: {}", event);  // Authorized[paymentId=P-1, amountCents=50000, ...]

Best practices

• Model payment events as sealed interface + record implementations — exhaustive switch handlers.
• Validate in record compact constructor — IBAN format, positive amounts, non-blank IDs.
• Use records for DTOs, API responses, Kafka events — classes for JPA entities only.
• Remove default from switches on sealed types — let compiler enforce new cases.
• Prefer switch expressions over statement switches — no fall-through, assignable result.
• Document permitted types in architecture diagram — sealed permits is living documentation.
• Use record patterns in switch (Java 21) instead of manual getter extraction.

Anti-patterns

• Mutable record components — ArrayList modified after construction without defensive copy.
• String type field + switch default instead of sealed hierarchy.
• Record with 25 fields — still a god object; decompose into nested records.
• non-sealed everywhere — defeats purpose of closed hierarchy for payment SPI.
• Lombok @Data instead of record for pure DTO — record is simpler and correct by default.

Staff engineer notes

• Sealed + switch exhaustiveness catches the chargeback-default-branch bug at compile time — highest ROI Java 17 feature for fintech.
• Records replaced 60% of inner static POJO classes in mature codebases — review focuses on validation not boilerplate.
• If your switch still has default for domain type — you're not done migrating to sealed.
• Record patterns in Java 21 switch are the endgame for payment routing — readable and provably exhaustive.
• JPA entity vs record DTO boundary should be in team ADR — biggest adoption friction point.

Interview questions

Hands-on exercise

Lab: Sealed payment events

• Run playground — observe routing for standard vs high-value Authorized.
• Add new permitted type Refunded — fix compile errors in switch.
• Add compact constructor validation on Declined (non-blank reasonCode).
• Convert extractAmount to switch expression instead of instanceof if.
• Write Jackson @JsonSubTypes sketch for polymorphic deserialization.
• Bonus: nested record for Money(long cents, Currency currency) inside Authorized.

Press Run to execute. Real javac + JVM via remote API. Falls back to simulator on network failure.

Architecture trade-offs

• Record vs class DTO: Record immutable and concise; class needed for JPA/builders.
• Sealed vs open hierarchy: Sealed exhaustive; open extensible but switch fragile.
• Switch expression vs if-else chain: Switch exhaustive on sealed; if-else flexible but verbose.
• Guarded patterns vs nested if: Guards declarative; nested if works on older Java.

Summary

Records, sealed classes, pattern matching, and switch expressions modernize payment domain modeling — immutable events, closed hierarchies, and exhaustive handlers that fail compilation instead of silently dropping chargebacks. Use records for DTOs and events, sealed for domain ADTs, switch expressions for routing. These Java 17–21 features are the baseline for enterprise code review in 2026.

Key takeaways

• Records are immutable DTOs/events — compiler generates equals, hashCode, accessors.
• Sealed classes restrict hierarchy — PaymentEvent permits only known outcomes.
• Pattern matching + switch expressions give exhaustive, compiler-checked routing.
• Validate in compact constructors — records don't prevent invalid component values without checks.
• Never use default switch branch for sealed payment events — silent drops cause financial incidents.