<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p><span style="color:#808080;font-style:italic;"><font
color="#000000">Draft spec, please comment.</font></span></p>
<p><span style="color:#808080;font-style:italic;"></span></p>
<pre style="background-color:#ffffff;color:#000000;font-family:'Consolas';font-size:11.3pt;"><span style="color:#808080;font-style:italic;">
/*
</span><span style="color:#808080;font-style:italic;"> * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
</span><span style="color:#808080;font-style:italic;"> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * This code is free software; you can redistribute it and/or modify it
</span><span style="color:#808080;font-style:italic;"> * under the terms of the GNU General Public License version 2 only, as
</span><span style="color:#808080;font-style:italic;"> * published by the Free Software Foundation. Oracle designates this
</span><span style="color:#808080;font-style:italic;"> * particular file as subject to the "Classpath" exception as provided
</span><span style="color:#808080;font-style:italic;"> * by Oracle in the LICENSE file that accompanied this code.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * This code is distributed in the hope that it will be useful, but WITHOUT
</span><span style="color:#808080;font-style:italic;"> * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
</span><span style="color:#808080;font-style:italic;"> * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
</span><span style="color:#808080;font-style:italic;"> * version 2 for more details (a copy is included in the LICENSE file that
</span><span style="color:#808080;font-style:italic;"> * accompanied this code).
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * You should have received a copy of the GNU General Public License version
</span><span style="color:#808080;font-style:italic;"> * 2 along with this work; if not, write to the Free Software Foundation,
</span><span style="color:#808080;font-style:italic;"> * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
</span><span style="color:#808080;font-style:italic;"> * or visit <a class="moz-txt-link-abbreviated" href="http://www.oracle.com">www.oracle.com</a> if you need additional information or have any
</span><span style="color:#808080;font-style:italic;"> * questions.
</span><span style="color:#808080;font-style:italic;"> */
</span><span style="color:#000080;font-weight:bold;">package </span>java.lang;
<span style="color:#808080;font-style:italic;">/**
</span><span style="color:#808080;font-style:italic;"> * This is the common base class of all Java language record classes.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><p></span><span style="color:#808080;font-style:italic;">More information about records, including descriptions of the
</span><span style="color:#808080;font-style:italic;"> * implicitly declared methods synthesized by the compiler, can be
</span><span style="color:#808080;font-style:italic;"> * found in section 8.10 of
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><cite></span><span style="color:#808080;font-style:italic;">The Java</span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;">™</span><span style="color:#808080;font-style:italic;"> Language Specification</span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"></cite></span><span style="color:#808080;font-style:italic;">.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><p></span><span style="color:#808080;font-style:italic;">A </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><em></span><span style="color:#808080;font-style:italic;">record class</span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"></em></span><span style="color:#808080;font-style:italic;"> is a shallowly immutable, transparent carrier for
</span><span style="color:#808080;font-style:italic;"> * a fixed set of values, called the </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><em></span><span style="color:#808080;font-style:italic;">record components</span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"></em></span><span style="color:#808080;font-style:italic;">. The Java</span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;">™</span><span style="color:#808080;font-style:italic;">
</span><span style="color:#808080;font-style:italic;"> * language provides concise syntax for declaring record classes, whereby the
</span><span style="color:#808080;font-style:italic;"> * record components are declared in the record header. The list of record
</span><span style="color:#808080;font-style:italic;"> * components declared in the record header form the </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><em></span><span style="color:#808080;font-style:italic;">record descriptor</span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"></em></span><span style="color:#808080;font-style:italic;">.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><p></span><span style="color:#808080;font-style:italic;">A record class has the following mandated members: a public </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><em></span><span style="color:#808080;font-style:italic;">canonical
</span><span style="color:#808080;font-style:italic;"> * constructor</span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"></em></span><span style="color:#808080;font-style:italic;">, whose descriptor is the same as the record descriptor;
</span><span style="color:#808080;font-style:italic;"> * a private static field corresponding to each component, whose name and
</span><span style="color:#808080;font-style:italic;"> * type are the same as that of the component; a public accessor method
</span><span style="color:#808080;font-style:italic;"> * corresponding to each component, whose name and return type are the same as
</span><span style="color:#808080;font-style:italic;"> * that of the component. If not explicitly declared in the body of the record,
</span><span style="color:#808080;font-style:italic;"> * implicit implementations for these members are provided.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><p></span><span style="color:#808080;font-style:italic;">The implicit declaration of the canonical constructor initializes the
</span><span style="color:#808080;font-style:italic;"> * component fields from the corresponding constructor arguments. The implicit
</span><span style="color:#808080;font-style:italic;"> * declaration of the accessor methods returns the value of the corresponding
</span><span style="color:#808080;font-style:italic;"> * component field. The implicit declaration of the {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@link </span><span style="color:#808080;font-style:italic;">Object#equals(Object)},
</span><span style="color:#808080;font-style:italic;"> * {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@link </span><span style="color:#808080;font-style:italic;">Object#hashCode()}, and {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@link </span><span style="color:#808080;font-style:italic;">Object#toString()} methods are derived
</span><span style="color:#808080;font-style:italic;"> * from all of the component fields.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><p></span><span style="color:#808080;font-style:italic;">The primary reasons to provide an explicit declaration for the
</span><span style="color:#808080;font-style:italic;"> * canonical constructor or accessor methods are to validate constructor
</span><span style="color:#808080;font-style:italic;"> * arguments, perform defensive copies on mutable components, or normalize groups
</span><span style="color:#808080;font-style:italic;"> * of components (such as reducing a rational number to lowest terms.) If any
</span><span style="color:#808080;font-style:italic;"> * of these are provided explicitly.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><p></span><span style="color:#808080;font-style:italic;">For all record classes, the following invariant must hold: if a record R's
</span><span style="color:#808080;font-style:italic;"> * components are {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@code </span><span style="color:#808080;font-style:italic;">c1, c2, ... cn}, then if a record instance is copied
</span><span style="color:#808080;font-style:italic;"> * as follows:
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"><pre></span><span style="color:#808080;font-style:italic;">
</span><span style="color:#808080;font-style:italic;"> * R copy = new R(r.c1(), r.c2(), ..., r.cn());
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;background-color:#e2ffe2;font-style:italic;"></pre></span><span style="color:#808080;font-style:italic;">
</span><span style="color:#808080;font-style:italic;"> * then it must be the case that {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@code </span><span style="color:#808080;font-style:italic;">r.equals(copy)}.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@jls </span><span style="color:#808080;font-style:italic;">8.10
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@since </span><span style="color:#808080;font-style:italic;">14
</span><span style="color:#808080;font-style:italic;"> */
</span><span style="color:#000080;font-weight:bold;">public abstract class </span>Record {
<span style="color:#808080;font-style:italic;">/**
</span><span style="color:#808080;font-style:italic;"> * Indicates whether some other object is "equal to" this one. In addition
</span><span style="color:#808080;font-style:italic;"> * to the general contract of {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@link </span><span style="color:#808080;font-style:italic;">Object#equals(Object)},
</span><span style="color:#808080;font-style:italic;"> * record classes must further participate in the invariant that when
</span><span style="color:#808080;font-style:italic;"> * a record instance is "copied" by passing the result of the record component
</span><span style="color:#808080;font-style:italic;"> * accessor methods to the canonical constructor, the resulting copy is
</span><span style="color:#808080;font-style:italic;"> * equal to the original instance.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@implNote
</span><span style="color:#808080;font-weight:bold;font-style:italic;"> </span><span style="color:#808080;font-style:italic;">* The implicitly provided implementation returns {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@code </span><span style="color:#808080;font-style:italic;">true} if and
</span><span style="color:#808080;font-style:italic;"> * only if the argument is an instance of the same record type as this object,
</span><span style="color:#808080;font-style:italic;"> * and each component of this record is equal to the corresponding component
</span><span style="color:#808080;font-style:italic;"> * of the argument, according to {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@link </span><span style="color:#808080;font-style:italic;">Object#equals(Object)} for components
</span><span style="color:#808080;font-style:italic;"> * whose types are reference types, and {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@code </span><span style="color:#808080;font-style:italic;">==} for components whose
</span><span style="color:#808080;font-style:italic;"> * types are primitive types.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@see </span><span style="color:#808080;font-style:italic;">Object#equals(Object)
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@param </span><span style="color:#3d3d3d;font-weight:bold;font-style:italic;">obj </span><span style="color:#808080;font-style:italic;">the reference object with which to compare.
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@return </span><span style="color:#808080;font-style:italic;">{</span><span style="color:#808080;font-weight:bold;font-style:italic;">@code </span><span style="color:#808080;font-style:italic;">true} if this object is the same as the obj
</span><span style="color:#808080;font-style:italic;"> * argument; {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@code </span><span style="color:#808080;font-style:italic;">false} otherwise.
</span><span style="color:#808080;font-style:italic;"> */
</span><span style="color:#808080;font-style:italic;"> </span><span style="color:#808000;">@Override
</span><span style="color:#808000;"> </span><span style="color:#000080;font-weight:bold;">public abstract boolean </span>equals(Object obj);
<span style="color:#808080;font-style:italic;">/**
</span><span style="color:#808080;font-style:italic;"> * {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@inheritDoc</span><span style="color:#808080;font-style:italic;">}
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@implNote
</span><span style="color:#808080;font-weight:bold;font-style:italic;"> </span><span style="color:#808080;font-style:italic;">* The implicitly provided implementation returns a hash code value derived
</span><span style="color:#808080;font-style:italic;"> * by combining the hash code value for all the components, according to
</span><span style="color:#808080;font-style:italic;"> * {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@link </span><span style="color:#808080;font-style:italic;">Object#hashCode()} for components whose types are reference types,
</span><span style="color:#808080;font-style:italic;"> * or the primitive wrapper hash code for components whose types are primitive
</span><span style="color:#808080;font-style:italic;"> * types.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@see </span><span style="color:#808080;font-style:italic;">Object#hashCode()
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@return </span><span style="color:#808080;font-style:italic;">a hash code value for this object.
</span><span style="color:#808080;font-style:italic;"> */
</span><span style="color:#808080;font-style:italic;"> </span><span style="color:#808000;">@Override
</span><span style="color:#808000;"> </span><span style="color:#000080;font-weight:bold;">public abstract int </span>hashCode();
<span style="color:#808080;font-style:italic;">/**
</span><span style="color:#808080;font-style:italic;"> * {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@inheritDoc</span><span style="color:#808080;font-style:italic;">}
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@implNote
</span><span style="color:#808080;font-weight:bold;font-style:italic;"> </span><span style="color:#808080;font-style:italic;">* The implicitly provided implementation returns a string that is derived
</span><span style="color:#808080;font-style:italic;"> * from the name of the record class and the names and string representations
</span><span style="color:#808080;font-style:italic;"> * of all the components, according to {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@link </span><span style="color:#808080;font-style:italic;">Object#toString()} for components
</span><span style="color:#808080;font-style:italic;"> * whose types are reference types, and the primitive wrapper {</span><span style="color:#808080;font-weight:bold;font-style:italic;">@code </span><span style="color:#808080;font-style:italic;">toString}
</span><span style="color:#808080;font-style:italic;"> * method for components whose types are primitive types.
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@see </span><span style="color:#808080;font-style:italic;">Object#toString() ()
</span><span style="color:#808080;font-style:italic;"> *
</span><span style="color:#808080;font-style:italic;"> * </span><span style="color:#808080;font-weight:bold;font-style:italic;">@return </span><span style="color:#808080;font-style:italic;">a string representation of the object.
</span><span style="color:#808080;font-style:italic;"> */
</span><span style="color:#808080;font-style:italic;"> </span><span style="color:#808000;">@Override
</span><span style="color:#808000;"> </span><span style="color:#000080;font-weight:bold;">public abstract </span>String toString();
}
</pre>
</body>
</html>