< prev index next > src/java.base/share/classes/java/lang/Object.java
Print this page
/*
! * Copyright (c) 1994, 2025, 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
/*
! * Copyright (c) 1994, 2026, 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
/**
* Class {@code Object} is the root of the class hierarchy.
* Every class has {@code Object} as a superclass. All objects,
* including arrays, implement the methods of this class.
*
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * When preview features are enabled, subclasses of {@code java.lang.Object}
+ * are either {@linkplain Class#isValue value classes} or identity classes.
+ * A <em>value object</em> is an instance of a non-abstract value class. All
+ * other objects, including arrays, are <em>identity objects</em>. See
+ * The Java Language Specification {@jls value-objects-8.1.1.5 Value Classes}.
+ * <p>
+ * All classes are identity classes and all objects are identity objects when
+ * preview features are disabled.
+ * <p>
+ * It is not possible to synchronize on a value object. An attempt to {@code
+ * synchronize} on a value object causes {@link IdentityException} to be thrown.
+ * <p>
+ * The {@link #finalize()} method of a value class will never be invoked by
+ * the garbage collector.
+ * <p>
+ * A {@linkplain java.lang.ref.Reference Reference Object} can only refer to an
+ * object with identity. Creating a reference object with a value object as
+ * the referent throws {@code IdentityException}.
+ * </div>
+ * </div>
+ *
* @see java.lang.Class
* @since 1.0
*/
@AOTSafeClassInitializer // for hierarchy checks
public class Object {
* @implSpec
* The {@code equals} method for class {@code Object} implements
* the most discriminating possible equivalence relation on objects;
* that is, for any non-null reference values {@code x} and
* {@code y}, this method returns {@code true} if and only
! * if {@code x} and {@code y} refer to the same object
* ({@code x == y} has the value {@code true}).
*
* In other words, under the reference equality equivalence
* relation, each equivalence class only has a single element.
*
* @implSpec
* The {@code equals} method for class {@code Object} implements
* the most discriminating possible equivalence relation on objects;
* that is, for any non-null reference values {@code x} and
* {@code y}, this method returns {@code true} if and only
! * if {@code x} and {@code y} refer to the same identity object or
+ * both refer to statewise-equivalent value objects
* ({@code x == y} has the value {@code true}).
*
* In other words, under the reference equality equivalence
* relation, each equivalence class only has a single element.
*
}
/**
* Creates and returns a copy of this object. The precise meaning
* of "copy" may depend on the class of the object. The general
! * intent is that, for any object {@code x}, the expression:
* <blockquote>
* <pre>
* x.clone() != x</pre></blockquote>
* will be true, and that the expression:
* <blockquote>
* <pre>
* x.clone().getClass() == x.getClass()</pre></blockquote>
! * will be {@code true}, but these are not absolute requirements.
* While it is typically the case that:
* <blockquote>
* <pre>
* x.clone().equals(x)</pre></blockquote>
* will be {@code true}, this is not an absolute requirement.
* <p>
! * By convention, the returned object should be obtained by calling
! * {@code super.clone}. If a class and all of its superclasses (except
! * {@code Object}) obey this convention, it will be the case that
! * {@code x.clone().getClass() == x.getClass()}.
* <p>
* By convention, the object returned by this method should be independent
* of this object (which is being cloned). To achieve this independence,
* it may be necessary to modify one or more fields of the object returned
* by {@code super.clone} before returning it. Typically, this means
}
/**
* Creates and returns a copy of this object. The precise meaning
* of "copy" may depend on the class of the object. The general
! * intent is that, for any identity object {@code x}, the expression:
* <blockquote>
* <pre>
* x.clone() != x</pre></blockquote>
* will be true, and that the expression:
* <blockquote>
* <pre>
* x.clone().getClass() == x.getClass()</pre></blockquote>
! * will be {@code true} for any object, but these are not absolute requirements.
* While it is typically the case that:
* <blockquote>
* <pre>
* x.clone().equals(x)</pre></blockquote>
* will be {@code true}, this is not an absolute requirement.
* <p>
! * By convention, the {@code clone} method of an identity class should return an
! * object obtained by calling {@code super.clone}. If a class and all of its
! * superclasses (except {@code Object}) obey this convention, it will be the
! * case that {@code x.clone().getClass() == x.getClass()}.
* <p>
* By convention, the object returned by this method should be independent
* of this object (which is being cloned). To achieve this independence,
* it may be necessary to modify one or more fields of the object returned
* by {@code super.clone} before returning it. Typically, this means
* of the object being cloned and replacing the references to these
* objects with references to the copies. If a class contains only
* primitive fields or references to immutable objects, then it is usually
* the case that no fields in the object returned by {@code super.clone}
* need to be modified.
*
* @implSpec
* The method {@code clone} for class {@code Object} performs a
* specific cloning operation. First, if the class of this object does
* not implement the interface {@code Cloneable}, then a
* {@code CloneNotSupportedException} is thrown. Note that all arrays
* are considered to implement the interface {@code Cloneable} and that
* the return type of the {@code clone} method of an array type {@code T[]}
* is {@code T[]} where T is any reference or primitive type.
! * Otherwise, this method creates a new instance of the class of this
! * object and initializes all its fields with exactly the contents of
* the corresponding fields of this object, as if by assignment; the
* contents of the fields are not themselves cloned. Thus, this method
* performs a "shallow copy" of this object, not a "deep copy" operation.
* <p>
* The class {@code Object} does not itself implement the interface
* {@code Cloneable}, so calling the {@code clone} method on an object
* whose class is {@code Object} will result in throwing an
* exception at run time.
*
* of the object being cloned and replacing the references to these
* objects with references to the copies. If a class contains only
* primitive fields or references to immutable objects, then it is usually
* the case that no fields in the object returned by {@code super.clone}
* need to be modified.
+ * <p>
+ * For a value object {@code x}, the expectation that {@code x.clone() != x} is not
+ * meaningful. Value classes that contain references to identity objects may override
+ * {@code clone} to perform a "deep copy" of the identity objects, returning an object
+ * with references to the copied identity objects.
+ *
+ * @apiNote
+ * It should be rare for new classes to implement the {@link Cloneable} interface.
+ * Copy constructors and static factory methods provide a more explicit and flexible
+ * means of creating copies, allowing classes to define and document their copying
+ * semantics without the constraints imposed by {@code Cloneable} interface and
+ * the {@code clone} method.
*
* @implSpec
* The method {@code clone} for class {@code Object} performs a
* specific cloning operation. First, if the class of this object does
* not implement the interface {@code Cloneable}, then a
* {@code CloneNotSupportedException} is thrown. Note that all arrays
* are considered to implement the interface {@code Cloneable} and that
* the return type of the {@code clone} method of an array type {@code T[]}
* is {@code T[]} where T is any reference or primitive type.
! * <p>
! * For an identity object, this method creates a new instance of the class of
+ * this object and initializes all its fields with exactly the contents of
* the corresponding fields of this object, as if by assignment; the
* contents of the fields are not themselves cloned. Thus, this method
* performs a "shallow copy" of this object, not a "deep copy" operation.
* <p>
+ * For a value object, this method returns an object that is <em>statewise
+ * equivalent</em> to this object.
+ * <p>
* The class {@code Object} does not itself implement the interface
* {@code Cloneable}, so calling the {@code clone} method on an object
* whose class is {@code Object} will result in throwing an
* exception at run time.
*
* <li>For objects of type {@code Class,} by executing a
* static synchronized method of that class.
* </ul>
* <p>
* Only one thread at a time can own an object's monitor.
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * The {@code notify} method requires that the current thread be the owner
+ * of the object's monitor. Since it is not possible to synchronize on a
+ * value object, an attempt to call this method on a value object will
+ * always fail with {@code IllegalMonitorStateException}.
+ * </div>
+ * </div>
*
* @throws IllegalMonitorStateException if the current thread is not
* the owner of this object's monitor.
* @see java.lang.Object#notifyAll()
* @see java.lang.Object#wait()
* This method should only be called by a thread that is the owner
* of this object's monitor. See the {@code notify} method for a
* description of the ways in which a thread can become the owner of
* a monitor.
*
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * The {@code notifyAll} method requires that the current thread be the owner
+ * of the object's monitor. Since it is not possible to synchronize on a
+ * value object, an attempt to call this method on a value object will
+ * always fail with {@code IllegalMonitorStateException}.
+ * </div>
+ * </div>
+ *
* @throws IllegalMonitorStateException if the current thread is not
* the owner of this object's monitor.
* @see java.lang.Object#notify()
* @see java.lang.Object#wait()
*/
* <p>
* In all respects, this method behaves as if {@code wait(0L, 0)}
* had been called. See the specification of the {@link #wait(long, int)} method
* for details.
*
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * The {@code wait} method requires that the current thread be the owner
+ * of the object's monitor. Since it is not possible to synchronize on a
+ * value object, an attempt to call this method on a value object will
+ * always fail with {@code IllegalMonitorStateException}.
+ * </div>
+ * </div>
+ *
* @throws IllegalMonitorStateException if the current thread is not
* the owner of the object's monitor
* @throws InterruptedException if any thread interrupted the current thread before or
* while the current thread was waiting. The <em>interrupted status</em> of the
* current thread is cleared when this exception is thrown.
* <p>
* In all respects, this method behaves as if {@code wait(timeoutMillis, 0)}
* had been called. See the specification of the {@link #wait(long, int)} method
* for details.
*
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * The {@code wait} method requires that the current thread be the owner
+ * of the object's monitor. Since it is not possible to synchronize on a
+ * value object, an attempt to call this method on a value object will
+ * always fail with {@code IllegalMonitorStateException}.
+ * </div>
+ * </div>
+ *
* @param timeoutMillis the maximum time to wait, in milliseconds
* @throws IllegalArgumentException if {@code timeoutMillis} is negative
* @throws IllegalMonitorStateException if the current thread is not
* the owner of the object's monitor
* @throws InterruptedException if any thread interrupted the current thread before or
* by any thread before or while it is waiting, then an {@code InterruptedException}
* is thrown. The <em>interrupted status</em> of the current thread is cleared when
* this exception is thrown. This exception is not thrown until the lock status of
* this object has been restored as described above.
*
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * The {@code wait} method requires that the current thread be the owner
+ * of the object's monitor. Since it is not possible to synchronize on a
+ * value object, an attempt to call this method on a value object will
+ * always fail with {@code IllegalMonitorStateException}.
+ * </div>
+ * </div>
+ *
* @apiNote
* The recommended approach to waiting is to check the condition being awaited in
* a {@code while} loop around the call to {@code wait}, as shown in the example
* below. Among other things, this approach avoids problems that can be caused
* by spurious wakeups.
wait(timeoutMillis);
}
/**
! * Called by the garbage collector on an object when garbage collection
* determines that there are no more references to the object.
! * A subclass overrides the {@code finalize} method to dispose of
* system resources or to perform other cleanup.
* <p>
* <b>When running in a Java virtual machine in which finalization has been
! * disabled or removed, the garbage collector will never call
! * {@code finalize()}. In a Java virtual machine in which finalization is
* enabled, the garbage collector might call {@code finalize} only after an
* indefinite delay.</b>
* <p>
* The general contract of {@code finalize} is that it is invoked
* if and when the Java virtual
wait(timeoutMillis);
}
/**
! * Called by the garbage collector on an identity object when garbage collection
* determines that there are no more references to the object.
! * An identity class may override the {@code finalize} method to dispose of
* system resources or to perform other cleanup.
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * The {@code finalize} method of a value class is never directly
+ * invoked by the garbage collector. This includes the case where an
+ * abstract value class declares a {@code finalize} method and the
+ * class is extended by an identity class; the garbage collector never
+ * directly invokes the {@code finalize} method declared by the
+ * abstract value class.
+ * </div>
+ * </div>
* <p>
* <b>When running in a Java virtual machine in which finalization has been
! * disabled or removed, the garbage collector will never call {@code finalize()}
! * for any object. In a Java virtual machine in which finalization is
* enabled, the garbage collector might call {@code finalize} only after an
* indefinite delay.</b>
* <p>
* The general contract of {@code finalize} is that it is invoked
* if and when the Java virtual
< prev index next >