Java Records

A Java record is a special kind of class built for one job: holding a few pieces of data. Before records, a simple class for a point on a map needed fields, a constructor, getters, equals(), hashCode() and toString(), often 40 lines of code that said almost nothing. With a record, it's one line. In this lesson, you'll learn what Java generates for you, how to add validation with a compact constructor, why records are immutable, and when a normal class is still the better choice.

What is a record in Java?

A record is a class declared with the record keyword, followed by a list of components in parentheses. Each component is a piece of data the record carries. Records became a standard feature in Java 16, so they work on any Java 17+ setup.

public class MapPins {
    public static void main(String[] args) {
        Point cafe = new Point(3, 4);
        Point library = new Point(3, 4);
        Point park = new Point(-2, 7);

        System.out.println(cafe);                       // toString()
        System.out.println("x = " + cafe.x() + ", y = " + cafe.y());   // accessors
        System.out.println("cafe.equals(library): " + cafe.equals(library));
        System.out.println("cafe == library: " + (cafe == library));
        System.out.println("cafe.equals(park): " + cafe.equals(park));
    }
}

record Point(int x, int y) { }

Point[x=3, y=4]
x = 3, y = 4
cafe.equals(library): true
cafe == library: false
cafe.equals(park): false

That single line, record Point(int x, int y) { }, gave us a constructor, two accessor methods, a readable toString(), and an equals() that compares the data. cafe and library are still two separate objects (== is false), but they're equal by value.

What does Java generate for a record?

For every component, the compiler writes the boring code you learned in encapsulation and the Object class lessons:

The canonical constructor is simply the constructor that takes every component in order. Notice that the accessors are named x(), not getX().

Adding methods to a record

The curly braces after the components are a class body. You can add normal methods, static fields and static methods there. Let's model a line in a shopping cart:

public class CartLine {
    public static void main(String[] args) {
        Product headphones = new Product("  Wireless Headphones ", 59.99, 2);
        Product cable = new Product("USB-C Cable", 9.50, 3);

        System.out.println(headphones);
        System.out.printf("%s: $%.2f%n", headphones.name(), headphones.lineTotal());
        System.out.printf("%s: $%.2f%n", cable.name(), cable.lineTotal());
        System.out.printf("Cart total: $%.2f%n", headphones.lineTotal() + cable.lineTotal());
    }
}

record Product(String name, double price, int quantity) {

    // Compact constructor: runs before the fields are set
    Product {
        if (price < 0) {
            throw new IllegalArgumentException("Price can't be negative: " + price);
        }
        if (quantity < 1) {
            throw new IllegalArgumentException("Quantity must be at least 1");
        }
        name = name.trim();          // clean up the value before it is stored
    }

    // Records can have normal methods too
    double lineTotal() {
        return price * quantity;
    }
}

Product[name=Wireless Headphones, price=59.99, quantity=2]
Wireless Headphones: $119.98
USB-C Cable: $28.50
Cart total: $148.48

The extra spaces around " Wireless Headphones " disappeared, because the record cleaned up the name before storing it. That happened in the compact constructor.

How do compact constructors validate data?

A compact constructor is a special constructor for records, written with just the record name and no parameter list: Product { ... }. The parameters are there implicitly, with the same names as the components. Its code runs first, and then Java assigns the (possibly changed) parameters to the fields automatically.

It's the perfect place to validate data, so a record can never hold nonsense. If someone tries new Product("Mug", -5, 1), the throw statement stops the program with a clear message:

Exception in thread "main" java.lang.IllegalArgumentException: Price can't be negative: -5.0

throw raises an error on purpose. You'll learn all about it in Java throw and throws; for now, just know it refuses bad data.

Records are immutable

A record's fields are private final, and there are no setters. Once a record is created, its data never changes. An object like this is called immutable. To "change" a value, you create a new record, often with a small helper method:

public class PriceChange {
    public static void main(String[] args) {
        Product original = new Product("Desk Lamp", 24.00);
        Product onSale = original.withPrice(18.00);

        System.out.println("Original: " + original);
        System.out.println("On sale:  " + onSale);
        // original.price = 18.00;   // compile error: price is final
    }
}

record Product(String name, double price) {
    Product withPrice(double newPrice) {
        return new Product(name, newPrice);   // a new record; the old one is unchanged
    }
}

Original: Product[name=Desk Lamp, price=24.0]
On sale:  Product[name=Desk Lamp, price=18.0]

Writing original.price = 18.00 from outside fails with price has private access in Product, and even inside the record you'd get cannot assign a value to final variable price. Immutable objects are easy to reason about: you can share them anywhere without worrying that some other code will change them behind your back.

Records in a HashSet

Because equality is built in, records are great for things like coordinates or keys. Here a game remembers which grid cells a player has visited:

import java.util.HashSet;
import java.util.Set;

public class Visitors {
    public static void main(String[] args) {
        Set<GridCell> visited = new HashSet<>();
        visited.add(new GridCell(2, 5));
        visited.add(new GridCell(2, 5));   // equal record: not added again
        visited.add(new GridCell(0, 1));

        System.out.println("Cells visited: " + visited.size());
        System.out.println("Been to (2, 5)? " + visited.contains(new GridCell(2, 5)));
    }
}

record GridCell(int row, int col) { }

Cells visited: 2
Been to (2, 5)? true

Compare this with the Seat class in the previous lesson, which needed about 25 lines for the same behavior.

Record vs class: what's the difference?

When should you not use a record?

• The data must change over time. A bank account balance goes up and down; a game character moves. Use a normal class with encapsulated fields.
• You need inheritance. Records can't extend another class, and nothing can extend a record.
• You want to hide some of the data. Every component gets a public accessor and appears in toString(). A record holding a password would print it.
• Equality isn't "all fields equal". If two books are equal when only the ISBN matches, a record's generated equals() is wrong for you (you could override it, but then a class is usually clearer).

Common mistakes with records

1. Calling getX() instead of x()

Record accessors use the component name: point.x(). point.getX() gives cannot find symbol.

2. Adding an instance field

record Product(String name, double price) { int stock; } fails with field declaration must be static. All instance data must be a component in the parentheses.

3. Trying to extend a class

record Point(int x, int y) extends Shape doesn't compile. Records already extend java.lang.Record. Implement an interface instead.

4. Expecting a setter

There is no setPrice(). Create a new record with the new value, as withPrice() did above.

Practice exercise

public class WeatherStation {
    public static void main(String[] args) {
        Temperature[] readings = {
            new Temperature("London", 14.0),
            new Temperature("Dubai", 38.5),
            new Temperature("Oslo", -6.0)
        };

        for (Temperature t : readings) {
            System.out.printf("%s: %.1f C = %.1f F%n", t.city(), t.celsius(), t.fahrenheit());
        }
        System.out.println(readings[0]);
    }
}

record Temperature(String city, double celsius) {
    Temperature {
        if (celsius < -273.15) {
            throw new IllegalArgumentException("Below absolute zero: " + celsius);
        }
    }

    double fahrenheit() {
        return celsius * 9 / 5 + 32;
    }
}

London: 14.0 C = 57.2 F
Dubai: 38.5 C = 101.3 F
Oslo: -6.0 C = 21.2 F
Temperature[city=London, celsius=14.0]

What's next?

So far, every class, record and enum has lived side by side at the top level of a file. Java also lets you put a class inside another class. Next, learn when and why to do that in Java inner classes. Python has a similar idea called dataclasses, if you'd like to compare.