What Are Records in Java?

A record is a restricted form of class designed for carrying data. You declare the components in the header, and the compiler generates everything a data class needs: a private final field for each component, an all-args constructor that assigns them, accessors named after the component rather than getX, and equals, hashCode and toString based on the components.

import java.util.HashSet;
import java.util.List;
import java.util.Objects;

public class Main {
    public static void main(String[] args) {
        Point p = new Point(3, 4);
        System.out.println("point     : " + p);
        System.out.println("x         : " + p.x());
        System.out.println("equals    : " + p.equals(new Point(3, 4)));
        System.out.println("hashCode  : " + (p.hashCode() == new Point(3, 4).hashCode()));

        // Works as a map key and inside a set.
        var points = new HashSet<Point>(List.of(p, new Point(3, 4)));
        System.out.println("in a set  : " + points.size());
    }
}

// What a record compiles down to: a final class with a private final field
// per component, an all-args constructor, and accessors named after the
// component rather than getX.
final class Point {
    private final int x;
    private final int y;

    Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    int x() {
        return x;
    }

    int y() {
        return y;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof Point)) {
            return false;
        }
        Point other = (Point) o;
        return x == other.x && y == other.y;
    }

    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }

    @Override
    public String toString() {
        return "Point[x=" + x + ", y=" + y + "]";
    }
}

The sample above is that generated code written out by hand, so you can run it and see exactly what the compiler produces. The toString prints both components in a readable form, the accessors are named x and y rather than getX, two points with the same values are equal and share a hash code, and the set collapses them into a single entry.

Three things to notice about the design. The accessors are x() rather than getX(), which was a deliberate break with the JavaBean convention and gives records their own recognisable style. The class is implicitly final, because a record that could be subclassed could break the equals contract the compiler generated. And the components are implicitly final as well, because a mutable component would break the hash code the compiler generated.

Records also give you a compact form of inheritance that the class syntax cannot: a record may implement interfaces, so it can be a Comparable or a Serializable, but it cannot extend another class.

The limits come from one rule: a record is a shallowly immutable value. The components are final, but if a component is a mutable object the record does not become deeply immutable.

First, a record cannot extend a class. It can implement interfaces, but its superclass is always Object. If you need to share behaviour through inheritance, a record is the wrong tool.

Second, the fields are private final but there is no setter, and you cannot add one — a final field cannot be reassigned. If you need mutability, use a class.

Third, a mutable component leaks through. A record holding a List is only immutable if the List is itself unmodifiable. List.copyOf in the compact constructor makes it so, and that is the single most common thing to get wrong.

Fourth, you cannot add instance fields beyond the components. There is no place to cache a derived value. The workaround is to compute it on demand, or to make it a static field, or to use a plain class.

import java.util.Objects;
import java.util.Set;

public class Main {
    public static void main(String[] args) {
        Money ok = new Money(1250, "GBP");
        System.out.println("money     : " + ok);
        System.out.println("same value: " + ok.equals(new Money(1250, "GBP")));
        System.out.println("in a set  : " + new java.util.HashSet<>(java.util.List.of(ok, new Money(1250, "GBP"))).size());

        try {
            new Money(-1, "GBP");
        } catch (IllegalArgumentException e) {
            System.out.println("rejected  : " + e.getMessage());
        }
    }
}

// A value object with a validating constructor - the same shape a record's
// compact constructor would have.
final class Money {
    private final long amount;
    private final String currency;

    Money(long amount, String currency) {
        if (currency == null || currency.isBlank()) {
            throw new IllegalArgumentException("currency required");
        }
        if (amount < 0) {
            throw new IllegalArgumentException("amount must not be negative");
        }
        this.amount = amount;
        this.currency = currency;
    }

    long amount() {
        return amount;
    }

    String currency() {
        return currency;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof Money)) {
            return false;
        }
        Money other = (Money) o;
        return amount == other.amount && currency.equals(other.currency);
    }

    @Override
    public int hashCode() {
        return Objects.hash(amount, currency);
    }

    @Override
    public String toString() {
        return "Money[" + amount + " " + currency + "]";
    }
}

The sample above is that compact constructor written out by hand, so you can run it: the negative amount was rejected before the object existed, and the accessors work exactly like ordinary instance methods.

Two final points. A record can implement a custom equals and hashCode if the generated ones are not what you want — the compiler will not generate them if you declare them yourself. And a record's generated toString prints the component names, which is usually what you want in a log line.

Use a record when the type is a value: it has identity only through its contents, it is compared by value, and it is passed around rather than mutated. The classic examples are DTOs, API request and response bodies, domain events, and the elements of a value collection. A record gives you correct equals, hashCode and toString for free, which removes the single biggest source of boilerplate in ordinary Java.

Use a plain class when the type has behaviour, identity or lifecycle. A class with a method that computes something, or that holds a resource it must close, or whose identity matters independently of its contents — an order, a session, a service — should not be a record. The same goes for anything that needs to extend a base class or to be mutable.

Two design points that come up in interviews. First, a record gives you shallow immutability: the fields are final, but a mutable component still leaks. If you hold a collection, copy it in the compact constructor with List.copyOf. Second, the generated equals uses the component values, so two records with the same data are equal even if they came from different requests — which is exactly what you want for a value and exactly what you do not want for an entity.

The broader advice is that records push you towards immutable design, which is generally a good thing. When you find yourself wanting to change a record's component, that is often a signal that the field should not have been a component at all — that it was derived state, and the record should have computed it on demand.