Records in Java

Records became a standard feature in Java 16 (JEP 395), after previews in Java 14 and 15. Interviewers ask about them for two reasons. First, they're the modern answer to "write me an immutable value class", so a candidate who still hand-writes forty lines of getters looks out of date. Second, the details are subtle: what exactly is generated, why a record holding a List isn't really immutable, and why you can't use one as a JPA entity.

For this lesson, we'll focus on what the compiler generates (including the invokedynamic trick behind equals and toString), compact constructors, shallow immutability, the restrictions and why they exist, nested and local records, record patterns from Java 21, serialization, and how records compare with Lombok and ordinary classes.

01Picture it first: a sealed envelope with a window

Think of a record as a window envelope from your bank. The address on the front is the record header: it tells everyone exactly what's inside, and nothing else can be stuffed in later. Anyone can read the contents through the window (the accessors), but nobody can swap them once it's sealed (the final fields). Two envelopes with the same contents are treated as the same letter.

The "same contents means same letter" part is the key mental shift. An ordinary class has identity: two new User(...) objects are different users unless you write equals to say otherwise. A record says up front that it is its data. That's why Brian Goetz describes records as "nominal tuples": a tuple of values with a name and a type attached.

Here's what you write, next to what javac produces from it:

Fig. 1

On the left a one-line record declaration; on the right the class javac generates: final, extends Record, private final fields, canonical constructor, accessors, and equals, hashCode and toString delegating through invokedynamic to ObjectMethods.bootstrap

02What the compiler generates under the hood

public record Money(long amountMinor, String currency) {}

Money a = new Money(500, "INR");
Money b = new Money(500, "INR");
System.out.println(a == b);       // ?
System.out.println(a.equals(b));  // ?
System.out.println(a);            // ?

false
true
Money[amountMinor=500, currency=INR]

Run javap -p Money.class and you'll see the full list:

public final class Money extends java.lang.Record {
  private final long amountMinor;
  private final java.lang.String currency;
  public Money(long, java.lang.String);
  public final java.lang.String toString();
  public final int hashCode();
  public final boolean equals(java.lang.Object);
  public long amountMinor();
  public java.lang.String currency();
}

Notice four things:

1. The class is final and extends java.lang.Record. That's why a record can't extend anything else: Java has single inheritance and the slot is taken.
2. Every component becomes a private final field plus a public accessor with the same name. It's amountMinor(), not getAmountMinor(). Frameworks that look for JavaBean getters needed updates (Jackson added record support in 2.12).
3. The canonical constructor takes the components in declaration order and assigns them. a == b is still false: records are objects with their own identity, they don't use it for equals.
4. equals, hashCode and toString exist, but there's no Java code for them in the class file. Let's look at that next.

equals, hashCode and toString through invokedynamic

If you run javap -c on Money, the toString body is two instructions:

aload_0
invokedynamic #0:toString:(LMoney;)Ljava/lang/String;
areturn

The invokedynamic call site points to the bootstrap method java.lang.runtime.ObjectMethods.bootstrap, and the class file passes it the record class plus method handles for each field. The first time the call site runs, the bootstrap builds a method handle chain that reads each component and combines them. After that, the JVM links the call site permanently and the JIT inlines it like ordinary code.

Why not generate bytecode directly, the way Lombok or your IDE does? Two reasons. The class file stays small, because the logic lives in the JDK, not in every record. And the JDK can improve the implementation without recompiling your code, the same idea that string concatenation uses since Java 9 with StringConcatFactory.

The semantics are specified in the Record javadoc. Reference components are compared with Objects.equals. Primitive components are compared as if by the wrapper's compare method, so Double.NaN equals Double.NaN inside a record, unlike with ==. The hashCode combines component hashes, but the exact formula is unspecified, so never persist it.

Compact constructors: validate and normalise

A record's canonical constructor is generated for you, but you can take control of it. The usual way is a compact constructor: no parameter list, and the field assignments happen automatically at the end.

public record Money(long amountMinor, String currency) {
    public Money {
        if (amountMinor < 0) {
            throw new IllegalArgumentException("amount must be >= 0, got " + amountMinor);
        }
        Objects.requireNonNull(currency, "currency");
        currency = currency.toUpperCase(Locale.ROOT);   // reassigns the parameter, not the field
    }

    public Money plus(Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException("currency mismatch");
        }
        return new Money(Math.addExact(amountMinor, other.amountMinor), currency);
    }

    public static Money zero(String currency) {
        return new Money(0, currency);
    }
}

System.out.println(new Money(250, "inr"));   // prints: Money[amountMinor=250, currency=INR]

Notice three rules:

• The parameters (amountMinor, currency) are implicit, and you may reassign them. Whatever value they hold at the end is what goes into the fields.
• You can't write this.currency = ... in a compact constructor. It's a compile error, because the compiler assigns the fields after your body runs.
• The canonical constructor must be at least as accessible as the record. A public record with a private canonical constructor doesn't compile, so a record can't hide its constructor behind a factory the way a normal class can.

You can also add other constructors, but each must start by calling this(...), so every path goes through the canonical one. That's the guarantee: if your validation is in the canonical constructor, no Money can exist without passing it.