| /* |
| * Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| package java.lang; |
| |
| /** |
| * This is the common base class of all Java language record classes. |
| * |
| * <p>More information about records, including descriptions of the |
| * implicitly declared methods synthesized by the compiler, can be |
| * found in section 8.10 of |
| * <cite>The Java Language Specification</cite>. |
| * |
| * <p>A <em>record class</em> is a shallowly immutable, transparent carrier for |
| * a fixed set of values, called the <em>record components</em>. The Java |
| * language provides concise syntax for declaring record classes, whereby the |
| * record components are declared in the record header. The list of record |
| * components declared in the record header form the <em>record descriptor</em>. |
| * |
| * <p>A record class has the following mandated members: a <em>canonical |
| * constructor</em>, which must provide at least as much access as the record |
| * class and whose descriptor is the same as the record descriptor; |
| * a private final field corresponding to each component, whose name and |
| * type are the same as that of the component; a public accessor method |
| * corresponding to each component, whose name and return type are the same as |
| * that of the component. If not explicitly declared in the body of the record, |
| * implicit implementations for these members are provided. |
| * |
| * <p>The implicit declaration of the canonical constructor has the same accessibility |
| * as the record class and initializes the component fields from the corresponding |
| * constructor arguments. The implicit declaration of the accessor methods returns |
| * the value of the corresponding component field. The implicit declaration of the |
| * {@link Object#equals(Object)}, {@link Object#hashCode()}, and {@link Object#toString()} |
| * methods are derived from all of the component fields. |
| * |
| * <p>The primary reasons to provide an explicit declaration for the |
| * canonical constructor or accessor methods are to validate constructor |
| * arguments, perform defensive copies on mutable components, or normalize groups |
| * of components (such as reducing a rational number to lowest terms.) |
| * |
| * <p>For all record classes, the following invariant must hold: if a record R's |
| * components are {@code c1, c2, ... cn}, then if a record instance is copied |
| * as follows: |
| * <pre> |
| * R copy = new R(r.c1(), r.c2(), ..., r.cn()); |
| * </pre> |
| * then it must be the case that {@code r.equals(copy)}. |
| * |
| * @apiNote |
| * A record class that {@code implements} {@link java.io.Serializable} is said |
| * to be a <i>serializable record</i>. Serializable records are serialized and |
| * deserialized differently than ordinary serializable objects. During |
| * deserialization the record's canonical constructor is invoked to construct |
| * the record object. Certain serialization-related methods, such as readObject |
| * and writeObject, are ignored for serializable records. More information about |
| * serializable records can be found in the |
| * <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records"> |
| * <cite>Java Object Serialization Specification,</cite> Section 1.13, |
| * "Serialization of Records"</a>. |
| * |
| * @apiNote |
| * A record class structure can be obtained at runtime via reflection. |
| * See {@link Class#isRecord()} and {@link Class#getRecordComponents()} for more details. |
| * |
| * @jls 8.10 Record Types |
| * @since 16 |
| */ |
| public abstract class Record { |
| /** |
| * Constructor for record classes to call. |
| */ |
| protected Record() {} |
| |
| /** |
| * Indicates whether some other object is "equal to" this one. In addition |
| * to the general contract of {@link Object#equals(Object) Object.equals}, |
| * record classes must further obey the invariant that when |
| * a record instance is "copied" by passing the result of the record component |
| * accessor methods to the canonical constructor, as follows: |
| * <pre> |
| * R copy = new R(r.c1(), r.c2(), ..., r.cn()); |
| * </pre> |
| * then it must be the case that {@code r.equals(copy)}. |
| * |
| * @implSpec |
| * The implicitly provided implementation returns {@code true} if |
| * and only if the argument is an instance of the same record class |
| * as this record, and each component of this record is equal to |
| * the corresponding component of the argument; otherwise, {@code |
| * false} is returned. Equality of a component {@code c} is |
| * determined as follows: |
| * <ul> |
| * |
| * <li> If the component is of a reference type, the component is |
| * considered equal if and only if {@link |
| * java.util.Objects#equals(Object,Object) |
| * Objects.equals(this.c, r.c} would return {@code true}. |
| * |
| * <li> If the component is of a primitive type, using the |
| * corresponding primitive wrapper class {@code PW} (the |
| * corresponding wrapper class for {@code int} is {@code |
| * java.lang.Integer}, and so on), the component is considered |
| * equal if and only if {@code |
| * PW.compare(this.c, r.c)} would return {@code 0}. |
| * |
| * </ul> |
| * |
| * Apart from the semantics described above, the precise algorithm |
| * used in the implicitly provided implementation is unspecified |
| * and is subject to change. The implementation may or may not use |
| * calls to the particular methods listed, and may or may not |
| * perform comparisons in the order of component declaration. |
| * |
| * @see java.util.Objects#equals(Object,Object) |
| * |
| * @param obj the reference object with which to compare. |
| * @return {@code true} if this record is equal to the |
| * argument; {@code false} otherwise. |
| */ |
| @Override |
| public abstract boolean equals(Object obj); |
| |
| /** |
| * Returns a hash code value for the record. |
| * Obeys the general contract of {@link Object#hashCode Object.hashCode}. |
| * For records, hashing behavior is constrained by the refined contract |
| * of {@link Record#equals Record.equals}, so that any two records |
| * created from the same components must have the same hash code. |
| * |
| * @implSpec |
| * The implicitly provided implementation returns a hash code value derived |
| * by combining appropriate hashes from each component. |
| * The precise algorithm used in the implicitly provided implementation |
| * is unspecified and is subject to change within the above limits. |
| * The resulting integer need not remain consistent from one |
| * execution of an application to another execution of the same |
| * application, even if the hashes of the component values were to |
| * remain consistent in this way. Also, a component of primitive |
| * type may contribute its bits to the hash code differently than |
| * the {@code hashCode} of its primitive wrapper class. |
| * |
| * @see Object#hashCode() |
| * |
| * @return a hash code value for this record. |
| */ |
| @Override |
| public abstract int hashCode(); |
| |
| /** |
| * Returns a string representation of the record. |
| * In accordance with the general contract of {@link Object#toString()}, |
| * the {@code toString} method returns a string that |
| * "textually represents" this record. The result should |
| * be a concise but informative representation that is easy for a |
| * person to read. |
| * <p> |
| * In addition to this general contract, record classes must further |
| * participate in the invariant that any two records which are |
| * {@linkplain Record#equals(Object) equal} must produce equal |
| * strings. This invariant is necessarily relaxed in the rare |
| * case where corresponding equal component values might fail |
| * to produce equal strings for themselves. |
| * |
| * @implSpec |
| * The implicitly provided implementation returns a string which |
| * contains the name of the record class, the names of components |
| * of the record, and string representations of component values, |
| * so as to fulfill the contract of this method. |
| * The precise format produced by this implicitly provided implementation |
| * is subject to change, so the present syntax should not be parsed |
| * by applications to recover record component values. |
| * |
| * @see Object#toString() |
| * |
| * @return a string representation of the object. |
| */ |
| @Override |
| public abstract String toString(); |
| } |
