1 /*
   2  * Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.lang;
  26 
  27 /**
  28  * {@preview Associated with records, a preview feature of the Java language.
  29  *
  30  *           This class is associated with <i>records</i>, a preview
  31  *           feature of the Java language. Programs can only use this
  32  *           class when preview features are enabled. Preview features
  33  *           may be removed in a future release, or upgraded to permanent
  34  *           features of the Java language.}
  35  *
  36  * This is the common base class of all Java language record classes.
  37  *
  38  * <p>More information about records, including descriptions of the
  39  * implicitly declared methods synthesized by the compiler, can be
  40  * found in section 8.10 of
  41  * <cite>The Java Language Specification</cite>.
  42  *
  43  * <p>A <em>record class</em> is a shallowly immutable, transparent carrier for
  44  * a fixed set of values, called the <em>record components</em>.  The Java
  45  * language provides concise syntax for declaring record classes, whereby the
  46  * record components are declared in the record header.  The list of record
  47  * components declared in the record header form the <em>record descriptor</em>.
  48  *
  49  * <p>A record class has the following mandated members: a <em>canonical
  50  * constructor</em>, which must provide at least as much access as the record
  51  * class and whose descriptor is the same as the record descriptor;
  52  * a private final field corresponding to each component, whose name and
  53  * type are the same as that of the component; a public accessor method
  54  * corresponding to each component, whose name and return type are the same as
  55  * that of the component.  If not explicitly declared in the body of the record,
  56  * implicit implementations for these members are provided.
  57  *
  58  * <p>The implicit declaration of the canonical constructor has the same accessibility
  59  * as the record class and initializes the component fields from the corresponding
  60  * constructor arguments.  The implicit declaration of the accessor methods returns
  61  * the value of the corresponding component field.  The implicit declaration of the
  62  * {@link Object#equals(Object)}, {@link Object#hashCode()}, and {@link Object#toString()}
  63  * methods are derived from all of the component fields.
  64  *
  65  * <p>The primary reasons to provide an explicit declaration for the
  66  * canonical constructor or accessor methods are to validate constructor
  67  * arguments, perform defensive copies on mutable components, or normalize groups
  68  * of components (such as reducing a rational number to lowest terms.)
  69  *
  70  * <p>For all record classes, the following invariant must hold: if a record R's
  71  * components are {@code c1, c2, ... cn}, then if a record instance is copied
  72  * as follows:
  73  * <pre>
  74  *     R copy = new R(r.c1(), r.c2(), ..., r.cn());
  75  * </pre>
  76  * then it must be the case that {@code r.equals(copy)}.
  77  *
  78  * @apiNote
  79  * A record class that {@code implements} {@link java.io.Serializable} is said
  80  * to be a <i>serializable record</i>. Serializable records are serialized and
  81  * deserialized differently than ordinary serializable objects. During
  82  * deserialization the record's canonical constructor is invoked to construct
  83  * the record object. Certain serialization-related methods, such as readObject
  84  * and writeObject, are ignored for serializable records. More information about
  85  * serializable records can be found in
  86  * <a href="{@docRoot}/java.base/java/io/ObjectInputStream.html#record-serialization">record serialization</a>.
  87  *
  88  * @jls 8.10 Record Types
  89  * @since 14
  90  */
  91 @jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.RECORDS,
  92                              essentialAPI=true)
  93 public abstract class Record {
  94     /**
  95      * Constructor for record classes to call.
  96      */
  97     protected Record() {}
  98 
  99     /**
 100      * Indicates whether some other object is "equal to" this one.  In addition
 101      * to the general contract of {@link Object#equals(Object) Object.equals},
 102      * record classes must further obey the invariant that when
 103      * a record instance is "copied" by passing the result of the record component
 104      * accessor methods to the canonical constructor, as follows:
 105      * <pre>
 106      *     R copy = new R(r.c1(), r.c2(), ..., r.cn());
 107      * </pre>
 108      * then it must be the case that {@code r.equals(copy)}.
 109      *
 110      * @implSpec
 111      * The implicitly provided implementation returns {@code true} if
 112      * and only if the argument is an instance of the same record type
 113      * as this record, and each component of this record is equal to
 114      * the corresponding component of the argument; otherwise, {@code
 115      * false} is returned. Equality of a component {@code c} is
 116      * determined as follows:
 117      * <ul>
 118      *
 119      * <li> If the component is of a reference type, the component is
 120      * considered equal if and only if {@link
 121      * java.util.Objects#equals(Object,Object)
 122      * Objects.equals(this.c(), r.c()} would return {@code true}.
 123      *
 124      * <li> If the component is of a primitive type, using the
 125      * corresponding primitive wrapper class {@code PW} (the
 126      * corresponding wrapper class for {@code int} is {@code
 127      * java.lang.Integer}, and so on), the component is considered
 128      * equal if and only if {@code
 129      * PW.valueOf(this.c()).equals(PW.valueOf(r.c()))} would return
 130      * {@code true}.
 131      *
 132      * </ul>
 133      *
 134      * Apart from the semantics described above, the precise algorithm
 135      * used in the implicitly provided implementation is unspecified
 136      * and is subject to change. The implementation may or may not use
 137      * calls to the particular methods listed, and may or may not
 138      * perform comparisons in the order of component declaration.
 139      *
 140      * @see java.util.Objects#equals(Object,Object)
 141      *
 142      * @param   obj   the reference object with which to compare.
 143      * @return  {@code true} if this record is equal to the
 144      *          argument; {@code false} otherwise.
 145      */
 146     @Override
 147     public abstract boolean equals(Object obj);
 148 
 149     /**
 150      * Returns a hash code value for the record.
 151      * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
 152      * For records, hashing behavior is constrained by the refined contract
 153      * of {@link Record#equals Record.equals}, so that any two records
 154      * created from the same components must have the same hash code.
 155      *
 156      * @implSpec
 157      * The implicitly provided implementation returns a hash code value derived
 158      * by combining appropriate hashes from each component.
 159      * The precise algorithm used in the implicitly provided implementation
 160      * is unspecified and is subject to change within the above limits.
 161      * The resulting integer need not remain consistent from one
 162      * execution of an application to another execution of the same
 163      * application, even if the hashes of the component values were to
 164      * remain consistent in this way.  Also, a component of primitive
 165      * type may contribute its bits to the hash code differently than
 166      * the {@code hashCode} of its primitive wrapper class.
 167      *
 168      * @see     Object#hashCode()
 169      *
 170      * @return  a hash code value for this record.
 171      */
 172     @Override
 173     public abstract int hashCode();
 174 
 175     /**
 176      * Returns a string representation of the record.
 177      * In accordance with the general contract of {@link Object#toString()},
 178      * the {@code toString} method returns a string that
 179      * "textually represents" this record. The result should
 180      * be a concise but informative representation that is easy for a
 181      * person to read.
 182      * <p>
 183      * In addition to this general contract, record classes must further
 184      * participate in the invariant that any two records which are
 185      * {@linkplain Record#equals(Object) equal} must produce equal
 186      * strings.  This invariant is necessarily relaxed in the rare
 187      * case where corresponding equal component values might fail
 188      * to produce equal strings for themselves.
 189      *
 190      * @implSpec
 191      * The implicitly provided implementation returns a string which
 192      * contains the name of the record class, the names of components
 193      * of the record, and string representations of component values,
 194      * so as to fulfill the contract of this method.
 195      * The precise format produced by this implicitly provided implementation
 196      * is subject to change, so the present syntax should not be parsed
 197      * by applications to recover record component values.
 198      *
 199      * @see     Object#toString()
 200      *
 201      * @return  a string representation of the object.
 202      */
 203     @Override
 204     public abstract String toString();
 205 }