Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java Record vs Immutable Class: Choosing the Right Data Carrier

Compare Java records and immutable classes for data modeling: syntax, equality, serialization, and when each approach fits better.

~5 min readJava
#Java records#immutable classes#data carriers#value objects
Side-by-side comparison of Java record and immutable class structures highlighting equality and data carrier design.

Choosing between a Java record and an immutable class is a common decision when modeling data carriers. Records, finalized in Java 16 after being previewed in Java 14 and 15, provide a compact syntax for classes that are transparent holders for immutable data. Immutable classes have existed since the beginning of Java and require more boilerplate but offer greater flexibility. The choice affects equality, serialization, inheritance, and maintainability.

What a Java Record Provides

A record declaration creates a final class with private final fields, a canonical constructor, accessor methods, and implementations of equals, hashCode, and toString based on all components. For example:

java
public record Point(int x, int y) {}

This single line gives you an immutable data carrier with structural equality. The compiler generates the constructor that assigns each field, accessors named after the components (x() and y()), and equals/hashCode methods that compare all components. Records cannot extend another class, cannot declare instance fields beyond the components, and are implicitly final.

What an Immutable Class Requires

An immutable class is a regular class that you design to prevent modification after construction. Typically you make fields private and final, provide a constructor that initializes them, expose getters instead of setters, and ensure no mutable objects are exposed. For example:

java
import java.util.Objects; public final class Point { private final int x; private final int y; public Point(int x, int y) { this.x = x; this.y = y; } public int x() { return x; } public int y() { return y; } @Override public boolean equals(Object o) { if (this == o) return true; if (!(o instanceof Point)) return false; Point p = (Point) o; return x == p.x && y == p.y; } @Override public int hashCode() { return Objects.hash(x, y); } }

The class is final to prevent subclassing, which could break immutability. You must implement equals and hashCode manually if you need value-based equality. This is where records reduce boilerplate significantly.

Equality and hashCode Behavior

Records derive equals and hashCode from all components. Two records are equal if their component values are equal, which is the behavior most data carriers need. For immutable classes, you decide which fields participate in equality. If you omit a field, two objects with different values for that field can still be equal; that may be intentional or a bug. Records use every component by default. If you need equality based on a subset of components, you must override equals and hashCode manually, which is possible but often not worth the complexity.

Serialization and Deserialization

Java serialization treats records specially when a record class implements Serializable. A record is not automatically serializable; it must declare Serializable like any other class. The serialized form is based on the record's components, and deserialization invokes the canonical constructor. This ensures that any validation or normalization in the constructor is reapplied. For an immutable class that implements Serializable, the default mechanism serializes the declared fields unless you customize writeObject and readObject. If the class has validation in its constructor, that validation is not run during deserialization unless you implement readObject to call the constructor. Records avoid that pitfall by design.

Inheritance and Extensibility

Records cannot extend any class and are implicitly final, though they can implement interfaces. This is a deliberate restriction. If you need to model a hierarchy of value types, you must use an abstract class or interface with immutable implementations. An immutable class can be designed to allow inheritance, but doing so requires careful attention to prevent subclasses from introducing mutable state or breaking equals symmetry. In practice, most data carriers are leaf types, so the record restriction is rarely a problem.

When to Choose a Record

Use a record when the data carrier is a simple aggregation of values with no additional behavior beyond accessors and value-based equality. Typical examples include DTOs, API responses, configuration tuples, and domain events. Records are also a good fit when you want the compiler to generate consistent equals and hashCode without maintenance. The compact syntax reduces the chance of errors when fields are added or removed.

When an Immutable Class Is Better

Choose an immutable class when you need more control than a record provides. For example, you may want to hide the constructor behind a factory method, cache instances, or normalize values before assignment. You might also need to implement an interface that requires methods not derived from components, or you want to use inheritance. Immutable classes also allow you to have fields that are not part of the equality contract, such as a cached hash code or a transient derived value.

Performance and Memory Considerations

Records and immutable classes have similar runtime characteristics. Both allocate objects on the heap, and both can benefit from defensive copying when a component is a mutable reference. Records do not automatically perform defensive copies; if a component is a mutable object, the record stores the reference. The same is true for an immutable class unless you implement copying in the constructor. For ordinary data carriers, performance is rarely the deciding factor between the two forms.

Common Pitfalls with Records

One common mistake is assuming that records are deeply immutable. A record with a component of type List or Date is not deeply immutable; the reference is final, but the referenced object can change. If you need deep immutability, you must either use immutable types or make defensive copies in the constructor. Another pitfall is relying on the default toString, which may expose sensitive data if the record contains credentials. Records do not provide any special protection; you must override toString if needed.

Making the Decision

The decision comes down to whether you need flexibility that a class provides beyond what a record offers. If a simple, final, value-based data carrier is sufficient, a record is usually the better choice because it reduces boilerplate and enforces consistent equality behavior. If you need custom construction logic, inheritance, or fields outside the component list, an immutable class gives you the control you need. For many modern Java codebases, records are a practical default for new data carriers; immutable classes remain useful when records cannot express the required design.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.