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 public <em>canonical 50 * constructor</em>, whose descriptor is the same as the record descriptor; 51 * a private final field corresponding to each component, whose name and 52 * type are the same as that of the component; a public accessor method 53 * corresponding to each component, whose name and return type are the same as 54 * that of the component. If not explicitly declared in the body of the record, 55 * implicit implementations for these members are provided. 56 * 57 * <p>The implicit declaration of the canonical constructor initializes the 58 * component fields from the corresponding constructor arguments. The implicit 59 * declaration of the accessor methods returns the value of the corresponding 60 * component field. The implicit declaration of the {@link Object#equals(Object)}, 61 * {@link Object#hashCode()}, and {@link Object#toString()} methods are derived 62 * from all of the component fields. 63 * 64 * <p>The primary reasons to provide an explicit declaration for the 65 * canonical constructor or accessor methods are to validate constructor 66 * arguments, perform defensive copies on mutable components, or normalize groups 67 * of components (such as reducing a rational number to lowest terms.) 68 * 69 * <p>For all record classes, the following invariant must hold: if a record R's 70 * components are {@code c1, c2, ... cn}, then if a record instance is copied 71 * as follows: 72 * <pre> 73 * R copy = new R(r.c1(), r.c2(), ..., r.cn()); 74 * </pre> 75 * then it must be the case that {@code r.equals(copy)}. 76 * 77 * @apiNote 78 * A record class that {@code implements} {@link java.io.Serializable} is said 79 * to be a <i>serializable record</i>. Serializable records are serialized and 80 * deserialized differently than ordinary serializable objects. During 81 * deserialization the record's canonical constructor is invoked to construct 82 * the record object. Certain serialization-related methods, such as readObject 83 * and writeObject, are ignored for serializable records. More information about 84 * serializable records can be found in 85 * <a href="{@docRoot}/java.base/java/io/ObjectInputStream.html#record-serialization">record serialization</a>. 86 * 87 * @jls 8.10 Record Types 88 * @since 14 89 */ 90 @jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.RECORDS, 91 essentialAPI=true) 92 public abstract class Record { 93 /** 94 * Constructor for record classes to call. 95 */ Record()96 protected Record() {} 97 98 /** 99 * Indicates whether some other object is "equal to" this one. In addition 100 * to the general contract of {@link Object#equals(Object) Object.equals}, 101 * record classes must further obey the invariant that when 102 * a record instance is "copied" by passing the result of the record component 103 * accessor methods to the canonical constructor, as follows: 104 * <pre> 105 * R copy = new R(r.c1(), r.c2(), ..., r.cn()); 106 * </pre> 107 * then it must be the case that {@code r.equals(copy)}. 108 * 109 * @implSpec 110 * The implicitly provided implementation returns {@code true} if 111 * and only if the argument is an instance of the same record type 112 * as this object, and each component of this record is equal to 113 * the corresponding component of the argument; otherwise, {@code 114 * false} is returned. Equality of a component {@code c} is 115 * determined as follows: 116 * <ul> 117 * 118 * <li> If the component is of a reference type, the component is 119 * considered equal if and only if {@link 120 * java.util.Objects#equals(Object,Object) 121 * Objects.equals(this.c(), r.c()} would return {@code true}. 122 * 123 * <li> If the component is of a primitive type, using the 124 * corresponding primitive wrapper class {@code PW} (the 125 * corresponding wrapper class for {@code int} is {@code 126 * java.lang.Integer}, and so on), the component is considered 127 * equal if and only if {@code 128 * PW.valueOf(this.c()).equals(PW.valueOf(r.c()))} would return 129 * {@code true}. 130 * 131 * </ul> 132 * 133 * The implicitly provided implementation conforms to the 134 * semantics described above; the implementation may or may not 135 * accomplish this by using calls to the particular methods 136 * listed. 137 * 138 * @see java.util.Objects#equals(Object,Object) 139 * 140 * @param obj the reference object with which to compare. 141 * @return {@code true} if this object is equal to the 142 * argument; {@code false} otherwise. 143 */ 144 @Override equals(Object obj)145 public abstract boolean equals(Object obj); 146 147 /** 148 * Obeys the general contract of {@link Object#hashCode Object.hashCode}. 149 * 150 * @implSpec 151 * The implicitly provided implementation returns a hash code value derived 152 * by combining the hash code value for all the components, according to 153 * {@link Object#hashCode()} for components whose types are reference types, 154 * or the primitive wrapper hash code for components whose types are primitive 155 * types. 156 * 157 * @see Object#hashCode() 158 * 159 * @return a hash code value for this object. 160 */ 161 @Override hashCode()162 public abstract int hashCode(); 163 164 /** 165 * Obeys the general contract of {@link Object#toString Object.toString}. 166 * 167 * @implSpec 168 * The implicitly provided implementation returns a string that is derived 169 * from the name of the record class and the names and string representations 170 * of all the components, according to {@link Object#toString()} for components 171 * whose types are reference types, and the primitive wrapper {@code toString} 172 * method for components whose types are primitive types. 173 * 174 * @see Object#toString() 175 * 176 * @return a string representation of the object. 177 */ 178 @Override toString()179 public abstract String toString(); 180 } 181