Draft specification for java.lang.Record

[Brian Goetz]

Re-sending as plain text, since the formatting got mangled by mailers.


/*
  * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License 
version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
package java.lang;

/**
  * This is the common base class of all Java language record classes.
  *
  * <p>More information about records, including descriptions of the
  * implicitly declared methods synthesized by the compiler, can be
  * found in section 8.10 of
  * <cite>The Java™ Language Specification</cite>.
  *
  * <p>A <em>record class</em> is a shallowly immutable, transparent 
carrier for
  * a fixed set of values, called the <em>record components</em>.  The 
Java™
  * language provides concise syntax for declaring record classes, 
whereby the
  * record components are declared in the record header.  The list of record
  * components declared in the record header form the <em>record 
descriptor</em>.
  *
  * <p>A record class has the following mandated members: a public 
<em>canonical
  * constructor</em>, whose descriptor is the same as the record descriptor;
  * a private static field corresponding to each component, whose name and
  * type are the same as that of the component; a public accessor method
  * corresponding to each component, whose name and return type are the 
same as
  * that of the component.  If not explicitly declared in the body of 
the record,
  * implicit implementations for these members are provided.
  *
  * <p>The implicit declaration of the canonical constructor initializes the
  * component fields from the corresponding constructor arguments. The 
implicit
  * declaration of the accessor methods returns the value of the 
corresponding
  * component field.  The implicit declaration of the {@link 
Object#equals(Object)},
  * {@link Object#hashCode()}, and {@link Object#toString()} methods are 
derived
  * from all of the component fields.
  *
  * <p>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 (such as reducing a rational number to lowest terms.)  
If any
  * of these are provided explicitly.
  *
  * <p>For all record classes, the following invariant must hold: if a 
record R's
  * components are {@code c1, c2, ... cn}, then if a record instance is 
copied
  * as follows:
  * <pre>
  *     R copy = new R(r.c1(), r.c2(), ..., r.cn());
  * </pre>
  * then it must be the case that {@code r.equals(copy)}.
  *
  * @jls 8.10
  * @since 14
  */
public abstract class Record {
     /**
      * Indicates whether some other object is "equal to" this one.  In 
addition
      * to the general contract of {@link Object#equals(Object)},
      * record classes must further participate in the invariant that when
      * a record instance is "copied" by passing the result of the 
record component
      * accessor methods to the canonical constructor, the resulting copy is
      * equal to the original instance.
      *
      * @implNote
      * The implicitly provided implementation returns {@code true} if and
      * only if the argument is an instance of the same record type as 
this object,
      * and each component of this record is equal to the corresponding 
component
      * of the argument, according to {@link Object#equals(Object)} for 
components
      * whose types are reference types, and {@code ==} for components whose
      * types are primitive types.
      *
      * @see Object#equals(Object)
      *
      * @param   obj   the reference object with which to compare.
      * @return  {@code true} if this object is the same as the obj
      *          argument; {@code false} otherwise.
      */
     @Override
     public abstract boolean equals(Object obj);

     /**
      * {@inheritDoc}
      *
      * @implNote
      * The implicitly provided implementation returns a hash code value 
derived
      * by combining the hash code value for all the components, 
according to
      * {@link Object#hashCode()} for components whose types are 
reference types,
      * or the primitive wrapper hash code for components whose types 
are primitive
      * types.
      *
      * @see     Object#hashCode()
      *
      * @return  a hash code value for this object.
      */
     @Override
     public abstract int hashCode();

     /**
      * {@inheritDoc}
      *
      * @implNote
      * The implicitly provided implementation returns a string that is 
derived
      * from the name of the record class and the names and string 
representations
      * of all the components, according to {@link Object#toString()} 
for components
      * whose types are reference types, and the primitive wrapper 
{@code toString}
      * method for components whose types are primitive types.
      *
      * @see     Object#toString() ()
      *
      * @return  a string representation of the object.
      */
     @Override
     public abstract String toString();
}



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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/amber-spec-experts/attachments/20190815/4906c734/attachment-0001.html>