Learning Tips | Published Nov 16, 2026 | 7 min read

Java Records and Record Classes

Learn Java record syntax, generated members, compact constructors, shallow immutability, equality, and when to use a regular class.

Diagram mapping Java record components to private final fields, accessors, constructor, equals, hashCode and toString with a shallow immutability note

Java records provide compact syntax for classes that primarily carry data. The compiler supplies component fields, accessors, a canonical constructor, equals, hashCode, and toString, while records remain ordinary reference types with specific limits. This guide covers record syntax, validation, shallow immutability, and when a regular class is still a better fit.

What a record declares

Records became a permanent Java feature in Java 16. A record declaration lists its components in the header; the compiler derives common members from those components:

public record Student(String name, int year) {}

This declares a record class with component fields and accessor methods name() and year(), along with a canonical constructor and value-oriented implementations of equals, hashCode, and toString. Accessors use the component name, not JavaBean-style getName().

Validate components in the canonical constructor

Use a compact canonical constructor when you need to validate or normalize input. Assignments to the record's component fields happen after the compact constructor body completes:

public record Student(String name, int year) {
    public Student {
        name = name.strip();
        if (name.isEmpty()) {
            throw new IllegalArgumentException("name is required");
        }
        if (year < 1) {
            throw new IllegalArgumentException("year must be positive");
        }
    }
}

Callers cannot bypass this constructor by using a different public constructor that omits the validation. If a record declares an additional constructor, it must delegate to the canonical constructor.

Records are shallowly immutable

A record is implicitly final, and its component fields are private and final. A record cannot declare additional instance fields or extend an arbitrary class; its direct superclass is java.lang.Record. It can implement interfaces and declare static fields, static methods, and instance methods.

Final component references do not make referenced objects immutable. Consider a record containing a mutable list:

public record Team(String name, List<String> members) {}

The reference cannot be reassigned through the record field, but callers may still mutate the list object. If the record should protect its data, defensively copy mutable inputs and avoid exposing mutable internals. List.copyOf(members) creates an unmodifiable list snapshot for typical collection components; the elements themselves may still be mutable.

Records therefore support a data-centric programming style, but they do not automatically provide deep immutability or thread safety.

Understand generated equality

The generated equals and hashCode use the record components. Two records of the same record class compare component values rather than object identity. This is useful for values such as coordinates, date ranges, or API response data.

Be careful when a component is a mutable object: changing its contents can affect equality or hash behavior. Do not mutate data used as a key in a hash-based collection. Arrays also have identity-based equality by default, so a record with an array component may not have the content-based equality some callers expect; use an appropriate immutable value type or explicitly define the intended behavior.

When to use a record

  • Use a record for a transparent data carrier whose identity is determined by its components.
  • Use a regular class when you need a mutable lifecycle, hidden representation, additional instance state, or a class hierarchy.
  • Use an interface when you need a capability contract that multiple unrelated implementations can provide; records can implement interfaces.
  • Consider validation and defensive copying where the record crosses a trust or ownership boundary.

Records are not a replacement for every POJO or entity. Frameworks may impose requirements on constructors, mutability, proxying, or naming conventions, so check the relevant framework's supported model before using records for persistence entities or binding objects.

A record can implement behavior too

Although records are concise data carriers, they can define methods that use their components:

public record Point(int x, int y) {
    public double distanceFromOrigin() {
        return Math.hypot(x, y);
    }
}

Keep methods closely related to the record's value. If a record begins accumulating unrelated responsibilities, split those into collaborating types.

Quick review checklist

  1. Does component-based equality match the meaning of this value?
  2. Are inputs validated in the canonical constructor?
  3. Can a referenced collection or array be mutated after construction?
  4. Does a framework or API require a particular constructor, accessor, or mutability pattern?
  5. Would a regular class communicate the behavior or lifecycle more clearly?

Records reduce boilerplate for a specific design: a final data-focused class whose components define its state. Choose one when that contract fits, and use defensive design when the data includes mutable references.

Further reading

Want a structured Java learning path?

Explore Jaipur Engineers course options to connect Java fundamentals, debugging, backend development and project practice in a guided learning plan.

Explore the Java program   Ask for course guidance