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 }