1 /*
2 * Copyright (c) 2019, 2026, 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 * This is the common base class of all Java language record classes.
29 *
30 * <p>More information about records, including descriptions of the
31 * implicitly declared methods synthesized by the compiler, can be
32 * found in section 8.10 of
33 * <cite>The Java Language Specification</cite>.
34 *
35 * <p>A <em>record class</em> is a shallowly immutable, transparent carrier for
36 * a fixed set of values, called the <em>record components</em>. The Java
37 * language provides concise syntax for declaring record classes, whereby the
38 * record components are declared in the record header. The list of record
39 * components declared in the record header form the <em>record descriptor</em>.
40 *
41 * <p>A record class has the following mandated members: a <em>canonical
42 * constructor</em>, which must provide at least as much access as the record
43 * class and whose descriptor is the same as the record descriptor;
44 * a private final field corresponding to each component, whose name and
45 * type are the same as that of the component; a public accessor method
46 * corresponding to each component, whose name and return type are the same as
47 * that of the component. If not explicitly declared in the body of the record,
48 * implicit implementations for these members are provided.
49 *
50 * <p>The implicit declaration of the canonical constructor has the same accessibility
51 * as the record class and initializes the component fields from the corresponding
52 * constructor arguments. The implicit declaration of the accessor methods returns
53 * the value of the corresponding component field. The implicit declaration of the
54 * {@link Object#equals(Object)}, {@link Object#hashCode()}, and {@link Object#toString()}
55 * methods are derived from all of the component fields.
56 *
57 * <p>The primary reasons to provide an explicit declaration for the
58 * canonical constructor or accessor methods are to validate constructor
59 * arguments, perform defensive copies on mutable components, or normalize groups
60 * of components (such as reducing a rational number to lowest terms.)
61 *
62 * <p>For all record classes, the following invariant must hold: if a record R's
63 * components are {@code c1, c2, ... cn}, then if a record instance is copied
64 * as follows:
65 * <pre>
66 * R copy = new R(r.c1(), r.c2(), ..., r.cn());
67 * </pre>
68 * then it must be the case that {@code r.equals(copy)}.
69 *
70 * <div class="preview-block">
71 * <div class="preview-comment">
72 * When preview features are enabled, {@code Record} is
73 * an abstract {@linkplain Class#isValue value class}.
74 * Subclasses of {@code Record} can be either identity classes
75 * or {@linkplain Class#isValue value classes}.
76 * See The Java Language Specification {@jls value-objects-8.1.1.5 Value Classes}.
77 * </div>
78 * </div>
79 *
80 * @apiNote
81 * A record class that {@code implements} {@link java.io.Serializable} is said
82 * to be a <i>serializable record</i>. Serializable records are serialized and
83 * deserialized differently than ordinary serializable objects. During
84 * deserialization the record's canonical constructor is invoked to construct
85 * the record object. Certain serialization-related methods, such as readObject
86 * and writeObject, are ignored for serializable records. More information about
87 * serializable records can be found in the
88 * <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
89 * <cite>Java Object Serialization Specification,</cite> Section 1.13,
90 * "Serialization of Records"</a>.
91 *
92 * @apiNote
93 * A record class structure can be obtained at runtime via reflection.
94 * See {@link Class#isRecord()} and {@link Class#getRecordComponents()} for more details.
95 *
96 * @spec serialization/index.html Java Object Serialization Specification
97 * @jls 8.10 Record Classes
98 * @since 16
99 */
100 // See doc/value-class-preview.md for an overview of value class generation
101 public abstract /*value*/ class Record {
102 /**
103 * Constructor for record classes to call.
104 */
105 protected Record() {}
106
107 /**
108 * Indicates whether some other object is "equal to" this one. In addition
109 * to the general contract of {@link Object#equals(Object) Object.equals},
110 * record classes must further obey the invariant that when
111 * a record instance is "copied" by passing the result of the record component
112 * accessor methods to the canonical constructor, as follows:
113 * <pre>
114 * R copy = new R(r.c1(), r.c2(), ..., r.cn());
115 * </pre>
116 * then it must be the case that {@code r.equals(copy)}.
117 *
118 * @implSpec
119 * The implicitly provided implementation returns {@code true} if
120 * and only if the argument is an instance of the same record class
121 * as this record, and each component of this record is equal to
122 * the corresponding component of the argument; otherwise, {@code
123 * false} is returned. Equality of a component {@code c} is
124 * determined as follows:
125 * <ul>
126 *
127 * <li> If the component is of a reference type, the component is
128 * considered equal if and only if {@link
129 * java.util.Objects#equals(Object,Object)
130 * Objects.equals(this.c, r.c)} would return {@code true}.
131 *
132 * <li> If the component is of a primitive type, using the
133 * corresponding primitive wrapper class {@code PW} (the
134 * corresponding wrapper class for {@code int} is {@code
135 * java.lang.Integer}, and so on), the component is considered
136 * equal if and only if {@code
137 * PW.compare(this.c, r.c)} would return {@code 0}.
138 *
139 * </ul>
140 *
141 * Note that these rules imply that {@linkplain
142 * Double##repEquivalence representation equivalence} is used for
143 * the equality comparison of both primitive floating-point values
144 * and wrapped floating-point values.
145 *
146 * <p>Apart from the semantics described above, the precise algorithm
147 * used in the implicitly provided implementation is unspecified
148 * and is subject to change. The implementation may or may not use
149 * calls to the particular methods listed, and may or may not
150 * perform comparisons in the order of component declaration.
151 *
152 * @see java.util.Objects#equals(Object,Object)
153 *
154 * @param obj the reference object with which to compare.
155 * @return {@code true} if this record is equal to the
156 * argument; {@code false} otherwise.
157 */
158 @Override
159 public abstract boolean equals(Object obj);
160
161 /**
162 * Returns a hash code value for the record.
163 * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
164 * For records, hashing behavior is constrained by the refined contract
165 * of {@link Record#equals Record.equals}, so that any two records
166 * created from the same components must have the same hash code.
167 *
168 * @implSpec
169 * The implicitly provided implementation returns a hash code value derived
170 * by combining appropriate hashes from each component.
171 * The precise algorithm used in the implicitly provided implementation
172 * is unspecified and is subject to change within the above limits.
173 * The resulting integer need not remain consistent from one
174 * execution of an application to another execution of the same
175 * application, even if the hashes of the component values were to
176 * remain consistent in this way. Also, a component of primitive
177 * type may contribute its bits to the hash code differently than
178 * the {@code hashCode} of its primitive wrapper class.
179 *
180 * @see Object#hashCode()
181 *
182 * @return a hash code value for this record.
183 */
184 @Override
185 public abstract int hashCode();
186
187 /**
188 * Returns a string representation of the record.
189 * In accordance with the general contract of {@link Object#toString()},
190 * the {@code toString} method returns a string that
191 * "textually represents" this record. The result should
192 * be a concise but informative representation that is easy for a
193 * person to read.
194 * <p>
195 * In addition to this general contract, record classes must further
196 * participate in the invariant that any two records which are
197 * {@linkplain Record#equals(Object) equal} must produce equal
198 * strings. This invariant is necessarily relaxed in the rare
199 * case where corresponding equal component values might fail
200 * to produce equal strings for themselves.
201 *
202 * @implSpec
203 * The implicitly provided implementation returns a string which
204 * contains the name of the record class, the names of components
205 * of the record, and string representations of component values,
206 * so as to fulfill the contract of this method.
207 * The precise format produced by this implicitly provided implementation
208 * is subject to change, so the present syntax should not be parsed
209 * by applications to recover record component values.
210 *
211 * @see Object#toString()
212 *
213 * @return a string representation of the object.
214 */
215 @Override
216 public abstract String toString();
217 }