1 /*
2 * Copyright (c) 2019, 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 * Indicates whether some other object is "equal to" this one. In addition
95 * to the general contract of {@link Object#equals(Object)},
96 * record classes must further participate in the invariant that when
97 * a record instance is "copied" by passing the result of the record component
98 * accessor methods to the canonical constructor, as follows:
99 * <pre>
100 * R copy = new R(r.c1(), r.c2(), ..., r.cn());
101 * </pre>
102 * then it must be the case that {@code r.equals(copy)}.
103 *
104 * @implSpec
105 * The implicitly provided implementation returns {@code true} if and
106 * only if the argument is an instance of the same record type as this object,
107 * and each component of this record is equal to the corresponding component
108 * of the argument, according to {@link java.util.Objects#equals(Object,Object)}
109 * for components whose types are reference types, and according to the semantics
110 * of the {@code equals} method on the corresponding primitive wrapper type.
111 *
112 * @see java.util.Objects#equals(Object,Object)
113 *
114 * @param obj the reference object with which to compare.
115 * @return {@code true} if this object is the same as the obj
116 * argument; {@code false} otherwise.
117 */
118 @Override
119 public abstract boolean equals(Object obj);
120
121 /**
122 * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
123 *
124 * @implSpec
125 * The implicitly provided implementation returns a hash code value derived
126 * by combining the hash code value for all the components, according to
127 * {@link Object#hashCode()} for components whose types are reference types,
128 * or the primitive wrapper hash code for components whose types are primitive
129 * types.
130 *
131 * @see Object#hashCode()
132 *
133 * @return a hash code value for this object.
134 */
135 @Override
136 public abstract int hashCode();
137
138 /**
139 * Obeys the general contract of {@link Object#toString Object.toString}.
140 *
141 * @implSpec
142 * The implicitly provided implementation returns a string that is derived
143 * from the name of the record class and the names and string representations
144 * of all the components, according to {@link Object#toString()} for components
145 * whose types are reference types, and the primitive wrapper {@code toString}
146 * method for components whose types are primitive types.
147 *
148 * @see Object#toString()
149 *
150 * @return a string representation of the object.
151 */
152 @Override
153 public abstract String toString();
154 }