Java Records (Java 16+) — Concise Immutable Data Carriers

Records (Java 16, JEP 395) are a concise way to declare immutable data carrier classes. One line: record User(Long id, String name, String email) {} and the compiler generates everything.

What the compiler generates

• Canonical constructor taking all fields
• Public accessor methods named after each field — id(), name() (NOT getId())
• equals and hashCode based on all components
• toString showing all fields

Implicit rules

• Records are final — can't be subclassed
• Records implicitly extend java.lang.Record — can't extend other classes
• Can implement interfaces
• All fields are private final

Compact constructor for validation/normalization

• public Money { Objects.requireNonNull(amount); currency = currency.toUpperCase(); }
• No parameter list — they're already in scope
• No this.x = x — assignment is automatic after the body
• Reassigning the parameter normalizes the value (field gets the new value)
• Throw to fail validation

You can add

• Custom methods
• Static factories
• Nested records
• Static fields/methods
• Non-canonical constructors (must delegate via this(...))

You CANNOT add

• Instance fields beyond components
• Mutable state
• Inheritance from other classes

Records pair perfectly with sealed types (Java 17) — ADTs

• sealed interface Shape permits Circle, Square with each subtype as a record
• Pattern matching switch (Java 21) deconstructs them
• case Circle(double r) -> Math.PI * r * r
• Compiler verifies exhaustiveness
• Same expressive power as Scala case classes or Rust enums

Best uses

• DTOs (request/response models)
• Value objects (Money, Coordinate, DateRange)
• Domain events
• Method return types for grouping multiple values
• Pattern matching with sealed types

When NOT to use records

1. JPA `@Entity`

• JPA needs no-arg constructor and mutable fields
• Records have neither
• Use a class for entities; map to records as DTOs

2. Identity-based objects

• A User identified by ID, not all fields
• Records auto-generate equals based on all fields — wrong
• Use a class with explicit equals based on ID

3. Mutable state

• Records have only final fields
• For mutable: use a class
• 'Wither' workaround: withName(String n) returns a new record

4. Complex inheritance

• Can implement interfaces, can't extend classes
• For shared implementation: composition

5. Defensive copies for mutable components

• Records hold references; List/Map components are still mutable through the reference
• Use List.copyOf(tags) in compact constructor for true immutability

Records vs Lombok `@Value`

• Records: native JDK, no annotation processor, work in IDEs without plugins
• Records: recognized by Jackson, Spring, Bean Validation natively
• Records: deconstruct in pattern matching switch (Java 21)
• Lombok still useful for @Builder, mutable @Data, @Slf4j — records don't replace those
• For new code: prefer records for pure immutable data

Records with Jackson

• Jackson 2.12+ recognizes records natively
• Deserializes via canonical constructor
• Field name matches JSON property by default

Records with Bean Validation

• Annotate components: record CreateRequest(@NotBlank String name, @Email String email) {}
• Works with Jakarta Validation 3.0+

Records with Spring Data — query projections

• DTO projections via SELECT new com.example.UserSummary(u.id, u.name) ...
• Interface-based projections also work

Records in Maps and Sets

• Work perfectly — equals/hashCode based on all components
• Useful as composite keys

Style recommendations

• DTOs, value objects, return-grouping, events: records
• Entities, services, mutable state, identity: classes
• Compact constructor for validation
• Defensive copy collection components
• Don't add many custom methods to records — if you need behavior, consider a class
• Single-component records are sometimes overkill — use the underlying type

Recommendation: Use records as your default for any immutable data carrier — DTOs, value objects, domain events, method return types that need to group multiple values. The 1-line declaration replaces 20+ lines of class boilerplate. Use a compact constructor for validation and normalization — fail fast on invalid input, normalize values (uppercase, strip whitespace, defensive copy collections). Pair records with sealed interfaces (Java 17) for ADT-style domain modeling — each variant is a record, the sealed type is the closed hierarchy, and pattern matching switch (Java 21) gives you compile-time exhaustive matching with deconstruction. Don't use records for JPA entities (need mutable state and no-arg constructor), identity-based objects (auto-generated equals is wrong for ID-based identity), or mutable state. Don't try to extend classes — records can only implement interfaces. Records win over Lombok `@Value` for new code: native to the JDK, no annotation processor, recognized by all tools, and they deconstruct in pattern matching. Lombok still has its place for @Builder and mutable @Data — they're not in competition for the same feature. The mental model: records are a class shorthand for immutable data with value semantics — nothing more, nothing less. They pair beautifully with sealed types, pattern matching, and the modern Java functional style.