1 /*
 2  * Copyright (c) 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 
26 package java.lang;
27 
28 /**
29  * A restricted interface implemented by all identity objects.
30 
31  * IdentityObject: An object with identity.
32  *
33  * *Identity* is a property of certain objects, determined at instance creation
34  * time and preserved throughout the life of the object. While an object's field
35  * values may change, its identity is constant. Object identities are unique: no
36  * two objects created by different instance creation operations can have the same
37  * identity.
38  *
39  * Every object is either an *identity object* or a *primitive object*. Primitive
40  * objects lack identity.
41  *
42  * The following operations have special behavior when applied to identity objects:
43  *
44  * - The `==` operator, and the default implementation of the `Object.equals`
45  * method, compare the identities of their operands, producing `true` for an
46  * identity object only if the object is being compared to itself.
47  *
48  * - The `System.identityHashCode` method, and the default implementation of the
49  * `Object.hashCode` method, generate a hash code from an identity object's
50  * identity.
51  *
52  * - The `synchronized` modifier and `synchronized` statement are only able to
53  * successfully acquire a lock when applied to an identity object.
54  *
55  * A class may implement `IdentityObject` or `PrimitiveObject`, but never both.
56  * Primitive classes always implement `PrimitiveObject`, while all other concrete
57  * classes (except `Object`) implicitly implement `IdentityObject`.
58  *
59  * Abstract classes and interfaces may implement or extend this interface if they
60  * wish to guarantee that all instances of the class or interface have identity.
61  *
62  * @since 1.16
63  */
64 public interface IdentityObject {
65 }