records

the picture

you know the class with two fields, a constructor, two getters, equals, hashCode and toString, fifty lines that all say "this is a pair of ints"? and how adding a third field means editing six places, and forgetting one of them is a bug? a record says the data once and derives the rest.

think of a form with labelled boxes. a record is the form: the boxes are the components, and once it's filled in and stamped, nobody can rub a box out. two forms with the same answers are the same form, as far as anyone cares.

public final class Point extends java.lang.Record {
  private final int x;
  private final int y;
  public Point(int, int);
  public final java.lang.String toString();
  public final int hashCode();
  public final boolean equals(java.lang.Object);
  public int x();
  public int y();
}

using one

record Point(int x, int y) {}
 
void main() {
    var p = new Point(1, 2);
    IO.println(p);                                   // toString
    IO.println(p.x() + p.y());                       // accessors
    IO.println(p.equals(new Point(1, 2)) + " " + (p == new Point(1, 2)));
    IO.println(p.hashCode() == new Point(1, 2).hashCode());
}

Point[x=1, y=2]
3
true false
true

equals compares values, == still compares identity: two different objects, equal contents. records can also have static fields, static methods, instance methods, nested types, and they can implement interfaces. what they can't have is extra state:

record R(int a) { int b; }
error: field declaration must be static
  (consider replacing field with record component)

compact constructors: validation without the boilerplate

the canonical constructor is generated, but you can write it yourself to check arguments. the compact form drops the parameter list and the field assignments: you write the checks, and the assignments happen after your code runs.

record Range(int lo, int hi) {
    Range {                                   // no (int lo, int hi), no this.lo = lo
        if (lo > hi) throw new IllegalArgumentException(lo + " > " + hi);
    }
}
 
void main() {
    IO.println(new Range(1, 5));
    IO.println(new Range(5, 1));
}

Range[lo=1, hi=5]
Exception in thread "main" java.lang.IllegalArgumentException: 5 > 1

inside a compact constructor, lo and hi are the parameters, and you can reassign them to normalize (hi = Math.max(hi, 0)). what you can't do is touch the fields: this.lo = lo there is error: cannot assign a value to final variable lo, because the compiler does that assignment itself, at the end.

shallowly immutable

the fields are final, so a record's components can never point somewhere else. but final is about the arrow, not the thing it points at:

record Team(String name, List<String> members) {}
 
var list = new ArrayList<>(List.of("ada"));
var t = new Team("core", list);
list.add("bob");          // t.members() now has bob

record Team(String name, List<String> members) {
    Team {
        Objects.requireNonNull(name);
        members = List.copyOf(members);
    }
}

List.copyOf makes an unmodifiable copy, so the record stops sharing the caller's list and t.members().add(...) throws UnsupportedOperationException. that's the record version of a defensive copy.

record Tagged(int[] data) {}
 
IO.println(new Tagged(new int[]{1}).equals(new Tagged(new int[]{1})));