Section 7.4
Records
Some programming languages have two basic kinds of built-in data structures: arrays and records. An array consists of a sequence of items, where individual items are referred to by their numerical position in the sequence. In a record, on the other hand, the positions in the data structure have names instead of numbers. The items in a record are called its "fields," and the names for the items are "field names." A field is accessed using its field name. We recognize records as similar to objects, with the fields in a record playing the same role as instance variables in an object, but records existed before object-oriented programming. The actual word "record" is used in programming languages such as Pascal and Cobol. The C programming language uses the term "struct" for the same idea. The "record" terminology might have originated with databases, which are just large, organized collections of data, where a record is a (typically small) set of related data items, and a database is a collection of records.
In Java, classes can be used to represent records, but the term "record" has not traditionally been used. However, in Java 17, records have become an official part of the language in the form of a special kind of class. Java records are not really equivalent to records in other languages, since a record in Java is immutable, that is, its content cannot be modified after the record is created. However, they are similar to other records is that they are fairly simple containers for named fields.
7.4.1 Basic Java Records
A Java record is an object that belongs to a special kind of class, which I will call a record class. In the simplest case, a record class specifies nothing but the set of instance variables that represent the fields of the record. Here is an example:
public record FullName(String firstName, String lastName) { }
This is a class definition for a record class named FullName that has two instance variables of type String named firstName and lastName. These instance variables are the fields of the record. The "{ }" at the end of the definition is an empty class body. Note that the instance variables in a record class are listed in parentheses after the class name. The syntax is the same as the syntax for a list of formal parameters in a method definition, but the meaning is very different. A record of type FullName—that is, an instance of the record class—is created in the usual way, with the new operator. For example,
FullName fname = new FullName("Jane", "Doe");
This statement calls a constructor that has one parameter for each field of the record, whose effect is simply to provide a value for each field. Note that this constructor was not explicitly defined in the class. It is called the canonical constructor for the record class, and it is provided automatically by the compiler. In fact, many things are added implicitly to a record class definition by the compiler. The simple record definition of FullName, given above, is essentially equivalent to the following regular class definition:
public final class FullName {
private final String firstName;
private final String lastName;
public FullName( String firstName, String lastName ) {
this.firstName = firstName;
this.lastName = lastName;
}
public firstName() {
return firstName;
}
public lastName() {
return lastName;
}
public String toString() {
return "FullName[firstName=" + firstName
+ ", lastName=" + lastName + "]";
}
public boolean equals(Object obj) {
// (definition omitted)
}
public int hashCode() {
// (definition omitted)
}
}
We see that a record class is automatically final, that is, it cannot be extended by subclasses. Furthermore, a record class cannot extend another class (but it is a subclass of Object, as is true for any class).
The instance variables in a record are private and final. Accessor, or "getter", methods for the instance variables are automatically defined, but instead of using the typical getXXX() naming convention for getter methods, their names are the same as the names of the instance variables. For example, if fname is a variable of type FullName, then the instance variables would be accessed as fname.firstName() and fname.lastName(). Because its instance variables are final, a record is immutable, so no "setter" methods can be defined.
Furthermore, reasonable definitions are automatically provided for three methods inherited from class Object: toString(), equals(), and hashCode(). The toString() method returns a string that includes the name of the class and the names and values of its fields. The equals() method returns true if its parameter is an object of the same type that has the same values for its fields. (We will not encounter the hashCode() method until Section 10.3.)
We will see that record class definitions can be more complex, but you should expect basic record classes, with empty class bodies, to be very common, since they provide a simple way to group together a set of related data items. For example, the CurveData class from the SimplePaint2.java example in the previous section was created to group together all the data relevant to a single curve:
private static class CurveData {
Color color;
boolean symmetric;
ArrayList<Point> points;
}
This nested class could be replaced by a nested record class:
private record CurveData(
Color color,
boolean symmetric,
ArrayList<Point> points
) { }
Note that the nested CurveData record class does not have to be declared static, because nested record classes are automatically static.
After this change, when a CurveData object is created, values must be provided for its fields. For example,
currentCurve = new CurveData(currentColor, useSymmetry, new ArrayList<Point>());
Another change is that CurveData objects are now immutable. That happens to be OK in SimplePaint2.java, but it's not something that will work in all cases. For example, class Point is a simple container for xy coordinates, but it could not be a record class because points are not immutable.
7.4.2 More Record Syntax
It is not possible to add additional instance variables to a record class, beyond those that are defined in the list after the class name. But almost anything else can be added in the class body. For example, a record class can contain static items of any kind. It can define instance methods, including replacements for the default toString(), equals(), and hashCode() methods. And it can define constructors, with just a few restrictions. First of all, it is possible to extend the definition for the canonical constructor that is defined automatically, using a syntax in which the parameter list for the constructor is omitted. For example, the canonical constructor for the FullName class might throw an exception if firstName is null:
public FullName { // canonical constructor for the FullName class
if ( firstName == null) {
throw new IllegalArgumentException("First name can't be null.");
}
}
This extends the canonical constructor. Although the parameter list is omitted in the definition, a call to this constructor still requires two parameters, and it still uses those parameters to initialize firstName and lastName, before the code in the constructor definition is executed.
Additional constructors can be defined, but any non-canonical constructor must begin with a call to a constructor in the same class, using the special variable this as discussed in Subsection 5.6.3. This means that the canonical constructor will be called, directly or indirectly, by any other constructor.
As an example, noting that there are people who use only a single name, we might want to provide a FullName constructor that takes just one parameter representing that name:
public FullName(String onlyName) {
this( onlyName, null ); // call the canonical constructor
}
This constructor calls the default constructor to set the firstName field equal to onlyName and the lastName field equal to null.
We might also want to define a more natural version of toString() for the FullName record class. For a full class definition that implements all of these ideas, see the sample file FullName.java.
A final syntax note: Although a record class cannot extend another class, it can implement one or more interfaces.
7.4.3 A Complex Example
A complex number consists of two real numbers, which are called the real part and the imaginary part of the complex number. Without knowing anything about the mathematics of complex numbers, you should see that this is a natural application for records. To represent a complex number in Java, we need a simple container for two values of type double. That could be done with a basic record class
record Complex( double re, double im ) { }
But there are many things that can be done with complex numbers, and we would want to include some of those things in a class that could truly be said to represent them. Here is a record class that includes a few of those things:
/**
* A record type for representing complex numbers, where
* a complex number consists of two real numbers called its
* real and imaginary parts. The class includes methods for
* doing arithmetic with complex numbers.
*/
public record Complex(double re, double im) {
// Some named constants for common complex numbers.
public final static Complex ONE = new Complex(1,0);
public final static Complex ZERO = new Complex(0,0);
public final static Complex I = new Complex(0,1);
/**
* This constructor creates a complex number with a given
* real part and with imaginary part zero.
*/
public Complex(double re) {
this(re,0);
}
/**
* Creates string representations of complex number such
* as: 3.0 + I*5.0, -I*3.14, 2.7 - I*8.6, 3.14
*/
public String toString() {
if (im == 0)
return String.valueOf(re);
else if (re == 0) {
if (im < 0)
return "-I*" + (-im);
else
return "I*" + im;
}
else if (im < 0)
return re + " - " + "I*" + (-im);
else
return re + " + " + "I*" + im;
}
// Some methods for doing arithmetic on two complex numbers
public Complex plus(Complex c) {
return new Complex(re + c.re, im + c.im);
}
public Complex minus(Complex c) {
return new Complex(re - c.re, im - c.im);
}
public Complex times(Complex c) {
return new Complex(re*c.re - im*c.im,
re*c.im + im*c.re);
}
public Complex dividedBy(Complex c) {
double denom = c.re*c.re + c.im*c.im;
double real = (re*c.re + im*c.im)/denom;
double imaginary = (im*c.re - re*c.im)/denom;
return new Complex(real,imaginary);
}
} // end record Complex
This class adds some static member variables, a constructor that creates a complex number from a single real number, a toString() method that prints a complex number in a reasonable format, and some instance variables that implement arithmetic operations on complex numbers. Of course, it also has the canonical constructor that creates a complex number from two real numbers. The sample program RecordDemo.java tests both Complex.java and FullName.java.
It might be worth thinking about why record classes should be final and why records should be immutable. One reason for them to be final is that it can make it possible for a complier to apply certain kinds of optimization to the code that it generates. This applies not just to record classes but to final classes in general.
Here is an example. It is common to compute complicated arithmetic expressions involving complex numbers. Consider the quadratic formula Ax2+Bx+C. If A, B, C, and x are objects of type Complex, then the value of this expression can be computed as
(A.times(x).times(x)).plus(B.times(x)).plus(C)
If you check the definitions of the times() and plus() methods, you can see that every time a method is called, it creates a new Complex object. In the quadratic formula example, five new objects are generated, but we are only interested in the one that represents the final answer. The other four objects are just scratch work: They are created, used very briefly and then immediately become eligible for garbage collection. Creating and garbage collecting large numbers of objects can be inefficient. However, in this case, the compiler might be able to avoid creating those extra objects by replacing the calls to plus() and times() with code that performs the same operations directly using temporary local variables of type double instead of objects. It can do this because it knows exactly what each method call does—but that is only the case because the Complex class is final. If that were not the case, then A, B, C, or x might actually refer to objects belonging to subclasses of Complex that have redefined plus() and times(). That is something that can only be checked at run time, not at compile time, so if the class were not final, a compiler would have no way of knowing what the calls to plus() and times() will do when the program is run.
As for immutability, it might also help with optimization, since a compiler can be sure that calling a method on an object will not modify the instance variables in that object. However, it is probably more important that immutability makes it easier to reason about a program. If you can prove that some property of an immutable object is true at some point in time, you can be sure that it won't become false later because the object has been modified.