1 /*
2 * Copyright (c) 2019, 2025, 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
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 * @apiNote
71 * A record class that {@code implements} {@link java.io.Serializable} is said
72 * to be a <i>serializable record</i>. Serializable records are serialized and
73 * deserialized differently than ordinary serializable objects. During
74 * deserialization the record's canonical constructor is invoked to construct
75 * the record object. Certain serialization-related methods, such as readObject
76 * and writeObject, are ignored for serializable records. More information about
77 * serializable records can be found in the
78 * <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
79 * <cite>Java Object Serialization Specification,</cite> Section 1.13,
80 * "Serialization of Records"</a>.
81 *
82 * @apiNote
83 * A record class structure can be obtained at runtime via reflection.
84 * See {@link Class#isRecord()} and {@link Class#getRecordComponents()} for more details.
85 *
86 * @spec serialization/index.html Java Object Serialization Specification
87 * @jls 8.10 Record Classes
88 * @since 16
89 */
90 public abstract class Record {
91 /**
92 * Constructor for record classes to call.
93 */
94 protected Record() {}
95
96 /**
97 * Indicates whether some other object is "equal to" this one. In addition
98 * to the general contract of {@link Object#equals(Object) Object.equals},
99 * record classes must further obey the invariant that when
100 * a record instance is "copied" by passing the result of the record component
101 * accessor methods to the canonical constructor, as follows:
102 * <pre>
103 * R copy = new R(r.c1(), r.c2(), ..., r.cn());
104 * </pre>
105 * then it must be the case that {@code r.equals(copy)}.
106 *
107 * @implSpec
108 * The implicitly provided implementation returns {@code true} if
109 * and only if the argument is an instance of the same record class
|
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
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 an {@linkplain Class#isIdentity identity class}
75 * or a {@linkplain Class#isValue value class}.
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 @jdk.internal.MigratedValueClass
101 @jdk.internal.ValueBased
102 public abstract class Record {
103 /**
104 * Constructor for record classes to call.
105 */
106 protected Record() {}
107
108 /**
109 * Indicates whether some other object is "equal to" this one. In addition
110 * to the general contract of {@link Object#equals(Object) Object.equals},
111 * record classes must further obey the invariant that when
112 * a record instance is "copied" by passing the result of the record component
113 * accessor methods to the canonical constructor, as follows:
114 * <pre>
115 * R copy = new R(r.c1(), r.c2(), ..., r.cn());
116 * </pre>
117 * then it must be the case that {@code r.equals(copy)}.
118 *
119 * @implSpec
120 * The implicitly provided implementation returns {@code true} if
121 * and only if the argument is an instance of the same record class
|