Skip to content

8387417: [lworld] API doc improvements for java.lang.Object #2588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlanBateman wants to merge 9 commits into
base: lworld
Choose a base branch
from
+257 −46
Open

8387417: [lworld] API doc improvements for java.lang.Object #2588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4a23687
Initial commit
AlanBateman Jun 25, 2026
4ee613e
Merge branch 'lworld' into Clone
AlanBateman Jun 26, 2026
7889c7d
More improvements
AlanBateman Jun 26, 2026
a56b3e3
More improvements
AlanBateman Jun 28, 2026
064fb54
More word smithing
AlanBateman Jun 29, 2026
780a704
Fix finalize spec
AlanBateman Jun 29, 2026
5a280a9
Adjust timeout
AlanBateman Jun 29, 2026
73f5445
Merge branch 'lworld' into Clone
AlanBateman Jun 30, 2026
dbc626a
Use statewise equivalent consistently
AlanBateman Jun 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 83 additions & 46 deletions src/java.base/share/classes/java/lang/Object.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,24 @@
*
* <div class="preview-block">
* <div class="preview-comment">
* When preview features are enabled, subclasses of {@code java.lang.Object} can be either
* identity classes or {@linkplain Class#isValue value classes}.
* See The Java Language Specification {@jls value-objects-8.1.1.5 Value Classes}.
* Use of value class instances for synchronization or with
* {@linkplain java.lang.ref.Reference object references} results in
* {@link IdentityException}.
* 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

@jaikiran jaikiran Jun 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello Alan, in several other places in the other JDK, we seem to refer to such classes as concrete value class. Should we do the same here instead of saying non-abstract value class?

@AlanBateman AlanBateman Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Defining a value object as an instance of non-abstract value classes works here, it's similar to the wording in the changes for the JLS.

@liach liach Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer to phrase it like "the class of a value object is a value class", more in line with code like o.getClass().isValue().

However, Valhalla models "identity" as the extra thing, so I guess it is better to go like "An identity object is an object whose class is an identity class or an array type. All other objects are value objects."

@AlanBateman AlanBateman Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer to keep this sentence as proposed as it keeps it consistent with the JLS and keeps the ordering that the terms are introduces consistent with the first sentence. I would be a bit wary of "All other objects are value objects" as it hints that there are other things that are also value classes.

* 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>
*
Expand Down Expand Up @@ -158,7 +170,8 @@ public Object() {}
* 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
* 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
Expand Down Expand Up @@ -186,25 +199,25 @@ public boolean equals(Object obj) {
/**
* 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:
* 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}, but these are not absolute requirements.
* 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 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()}.
* 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,
Expand All @@ -216,6 +229,18 @@ public boolean equals(Object obj) {
* 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
Expand All @@ -225,12 +250,16 @@ public boolean equals(Object obj) {
* 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
* <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
Expand Down Expand Up @@ -310,14 +339,15 @@ public String toString() {
* Only one thread at a time can own an object's monitor.
* <div class="preview-block">
* <div class="preview-comment">
* If this object is a {@linkplain java.util.Objects#hasIdentity value object},
* it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
* 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 or
* if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
* the owner of this object's monitor.
* @see java.lang.Object#notifyAll()
* @see java.lang.Object#wait()
*/
Expand All @@ -343,14 +373,15 @@ public String toString() {
*
* <div class="preview-block">
* <div class="preview-comment">
* If this object is a {@linkplain java.util.Objects#hasIdentity value object},
* it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
* 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 or
* if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
* the owner of this object's monitor.
* @see java.lang.Object#notify()
* @see java.lang.Object#wait()
*/
Expand All @@ -367,14 +398,15 @@ public String toString() {
*
* <div class="preview-block">
* <div class="preview-comment">
* If this object is a {@linkplain java.util.Objects#hasIdentity value object},
* it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
* 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 or
* if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
* 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.
Expand All @@ -398,16 +430,17 @@ public final void wait() throws InterruptedException {
*
* <div class="preview-block">
* <div class="preview-comment">
* If this object is a {@linkplain java.util.Objects#hasIdentity value object},
* it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
* 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 or
* if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
* 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.
Expand Down Expand Up @@ -502,8 +535,10 @@ public final void wait(long timeoutMillis) throws InterruptedException {
*
* <div class="preview-block">
* <div class="preview-comment">
* If this object is a {@linkplain java.util.Objects#hasIdentity value object},
* it does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
* 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>
*
Expand All @@ -529,8 +564,7 @@ public final void wait(long timeoutMillis) throws InterruptedException {
* @throws IllegalArgumentException if {@code timeoutMillis} is negative,
* or if the value of {@code nanos} is out of range
* @throws IllegalMonitorStateException if the current thread is not
* the owner of the object's monitor or
* if this object is a {@linkplain java.util.Objects#hasIdentity value object}.
* 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.
Expand All @@ -557,14 +591,24 @@ public final void wait(long timeoutMillis, int nanos) throws InterruptedExceptio
}

/**
* Called by the garbage collector on an object when garbage collection
* Called by the garbage collector on an identity object when garbage collection
* determines that there are no more references to the object.
* A subclass overrides the {@code finalize} method to dispose of
* 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()}. In a Java virtual machine in which finalization is
* 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>
Expand Down Expand Up @@ -607,13 +651,6 @@ public final void wait(long timeoutMillis, int nanos) throws InterruptedExceptio
* the finalization of this object to be halted, but is otherwise
* ignored.
*
* <div class="preview-block">
* <div class="preview-comment">
* If this object is a {@linkplain java.util.Objects#hasIdentity value object},
* this method will never be invoked by the garbage collector.
* </div>
* </div>
*
* @apiNote
* Classes that embed non-heap resources have many options
* for cleanup of those resources. The class must ensure that the
Expand Down
Loading