java.lang.Record: Draft Specification

Work on proposed Java Records continues to proceed. Brian Goetz started three new threads on the OpenJDK amber-spec-experts mailing list yesterday, and two of them are focused on Java Records. One of these two Record-oriented threads discusses whether Java records should support varargs. The other thread provides the initial draft specification for the proposed class java.lang.Record and that is the subject of this post.

The first sentence of the proposed class-level Javadoc for java.lang.Record currently says of this class, "This is the common base class of all Java language record classes." This initial specification also shows java.lang.Record being designated as a public abstract class.

Three "common" public abstract methods are explicitly declared in this initial specification of java.lang.Record: equals(Object), hashCode(), and toString(). All three methods are annotated with @Override and documented with {@inheritDoc} with Record specialization details. The specializations of the Javadoc for each of the three methods include Record-specific implementation notes using the @implNote tag. The class-level Javadoc tells us that these three "common" methods can be implicitly created: "The implicit declaration of the equals(Object), hashCode(), and toString() methods are derived from all of the component fields."

The proposed class-level Javadoc currently states: "A record class is a shallowly immutable, transparent carrier for a fixed set of values, called the record components." It also describes a "component field" as "a private static field corresponding to each component, whose name and type are the same as that of the component." The Javadoc states that these component fields are mandatory and adds that "a public accessor method corresponding to each component, whose name and return type are the same as that of the component" is also required. Further, the Javadoc adds that "implicit implementations for these members are provided" if none is expressed explicitly.

The proposed Javadoc also explains when one might choose to explicitly specify the Record constructor or accessor methods: "The primary reasons to provide an explicit declaration for the canonical constructor or accessor methods are to validate constructor arguments, perform defensive copies on mutable components, or normalize groups of components."

The draft specification for java.lang.Record adds concreteness to discussions regarding the implementation and use of Java Records. The proposed specification has already generated discussion on the amber-spec-experts mailing list. Topics discussed in relation to this specification include whether Records should prohibit cloning, whether to mention boxing of primitives in the equals method Javadoc, and whether Record.toString() and Enum.toString()should have warnings added to their Javadoc regarding changed output when a field is renamed.

The presentation of and discussion of a specification for java.lang.Record has heightened my anticipation for this feature from Project Amber.