The Canonical Constructor of a Record Class

Repeating the record class’s components in the signature of the canonical constructor can be tiresome and error-prone. To avoid this, you can declare a compact constructor whose signature is implicit (derived from the components automatically).

For example, the following compact constructor declaration validates length and width in the same way as in the previous example:

This succinct form of constructor declaration is only available in a record class. Note that the statements this.length = length; and this.width = width; which appear in the canonical constructor do not appear in the compact constructor. At the end of a compact constructor, its implicit formal parameters are assigned to the record class’s private fields corresponding to its components.

Explicit Declaration of Record Class Members

You can explicitly declare any of the members derived from the header, such as the public accessor methods that correspond to the record class’s components, for example:

If you implement your own accessor methods, then ensure that they have the same characteristics as implicitly derived accessors (for example, they’re declared public and have the same return type as the corresponding record class component). Similarly, if you implement your own versions of the equals, hashCode, and toString methods, then ensure that they have the same characteristics and behavior as those in the java.lang.Record class, which is the common superclass of all record classes.

You can declare static fields, static initializers, and static methods in a record class, and they behave as they would in a normal class, for example:

You cannot declare instance variables (non-static fields) or instance initializers in a record class.

For example, the following record class declaration doesn’t compile:

You can declare instance methods in a record class, independent of whether you implement your own accessor methods. You can also declare nested classes and interfaces in a record class, including nested record classes (which are implicitly static). For example:

You cannot declare native methods in a record class.

Features of Record Classes

A record class is implicitly final, so you cannot explicitly extend a record class. However, beyond these restrictions, record classes behave like normal classes:

• You can create a generic record class, for example:

  record Triangle<C extends Coordinate> (C top, C left, C right) { }

   
   

• You can declare a record class that implements one or more interfaces, for example:

  record Customer(...) implements Billable { }

   
   

• You can annotate a record class and its individual components, for example:

  import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface GreaterThanZero { }

   
  record Rectangle(
@GreaterThanZero double length,
@GreaterThanZero double width) { }

   
   

  If you annotate a record component, then the annotation may be propagated to members and constructors of the record class. This propagation is determined by the contexts in which the annotation interface is applicable. In the previous example, the @Target(ElementType.FIELD) meta-annotation means that the @GreaterThanZero annotation is propagated to the field corresponding to the record component. Consequently, this record class declaration would be equivalent to the following normal class declaration:

   

  public final class Rectangle {
private final @GreaterThanZero double length;
private final @GreaterThanZero double width;

  public Rectangle(double length, double width) {
  this.length = length;
  this.width = width;
  }

   

  double length() { return this.length; }
double width() { return this.width; }
} 

Record Classes and Sealed Classes and Interfaces

Record classes work well with sealed classes and interfaces. See below for an example:

You can name a record class in the permits clause of a sealed class or interface. See Record Classes for more information.

Record classes are implicitly final, so you can implement the previous example with record classes instead of ordinary classes:

Local Record Classes

A local record class is similar to a local class; it’s a record class defined in the body of a method.

In the following example, a merchant is modeled with a record class, Merchant. A sale made by a merchant is also modeled with a record class, Sale. Both Merchant and Sale are top-level record classes. The aggregation of a merchant and their total monthly sales is modeled with a local record class, MonthlySales, which is declared inside the findTopMerchants method. This local record class improves the readability of the stream operations that follow:

Static Members of Inner Classes

Prior to Java SE 16, you could not declare an explicitly or implicitly static member in an inner class unless that member is a constant variable. This means that an inner class cannot declare a record class member because nested record classes are implicitly static.

In Java SE 16 and later, an inner class may declare members that are either explicitly or implicitly static, which includes record class members. The following example demonstrates this:

You can serialize and deserialize instances of record classes, but you can’t customize the process by providing writeObject, readObject, readObjectNoData, writeExternal, or readExternal methods. The components of a record class govern serialization, while the canonical constructor of a record class governs deserialization. See Serializable Records for more information and an extended example. See also the section Serialization of Records in the Java Object Serialization Specification.

APIs Related to Record Classes

The abstract class java.lang.Record is the common superclass of all record classes.

You might get a compiler error if your source file imports a class named Record from a package other than java.lang. A Java source file automatically imports all the types in the java.lang package though an implicit import java.lang.*; statement. This includes the java.lang.Record class, regardless of whether preview features are enabled or disabled.

Both Record in the com.myapp package and Record in the java.lang package are imported with a wildcard. Consequently, neither class takes precedence, and the compiler generates an error when it encounters the use of the simple name Record.

To enable this example to compile, change the import statement so that it imports the fully qualified name of Record:

The class java.lang.Class has two methods related to record classes:

• RecordComponent[] getRecordComponents(): Returns an array of java.lang.reflect.RecordComponent objects, which correspond to the record class’s components.
• boolean isRecord(): Similar to isEnum() except that it returns true if the class was declared as a record class.