src/java.base/share/classes/java/lang/Object.java

*** 29,10 ***
--- 29,14 ---
  
  /**
   * 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.
+  * <p>
+  * Subclasses of {@code java.lang.Object} can be either an {@linkplain Class#isIdentity identity class}
+  * or a {@linkplain Class#isValue value class}.
+  * See {@jls The Java Language Specification 8.1.1.5 Value Classes}.
   *
   * @see     java.lang.Class
   * @since   1.0
   */
  public class Object {

*** 293,13 ***
       * <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.
       *
       * @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()
       */
      @IntrinsicCandidate
      public final native void notify();
--- 297,20 ---
       * <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">
+      *          If this object is a {@linkplain Class#isValue() value object},
+      *          it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
+      *      </div>
+      * </div>
       *
       * @throws  IllegalMonitorStateException  if the current thread is not
!      *               the owner of this object's monitor or
+      *               if this object is a {@linkplain Class#isValue() value object}.
       * @see        java.lang.Object#notifyAll()
       * @see        java.lang.Object#wait()
       */
      @IntrinsicCandidate
      public final native void notify();

*** 319,12 ***
       * 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.
       *
       * @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()
       */
      @IntrinsicCandidate
      public final native void notifyAll();
--- 330,20 ---
       * 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">
+      *          If this object is a {@linkplain Class#isValue() value object},
+      *          it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
+      *      </div>
+      * </div>
+      *
       * @throws  IllegalMonitorStateException  if the current thread is not
!      *               the owner of this object's monitor or
+      *               if this object is a {@linkplain Class#isValue() value object}.
       * @see        java.lang.Object#notify()
       * @see        java.lang.Object#wait()
       */
      @IntrinsicCandidate
      public final native void notifyAll();

*** 335,12 ***
       * <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.
       *
       * @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.
       * @see    #notify()
       * @see    #notifyAll()
--- 354,20 ---
       * <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">
+      *          If this object is a {@linkplain Class#isValue() value object},
+      *          it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
+      *      </div>
+      * </div>
+      *
       * @throws IllegalMonitorStateException if the current thread is not
!      *         the owner of the object's monitor or
+      *         if this object is a {@linkplain Class#isValue() value object}.
       * @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.
       * @see    #notify()
       * @see    #notifyAll()

*** 358,14 ***
       * <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.
       *
       * @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
       *         while the current thread was waiting. The <em>interrupted status</em> of the
       *         current thread is cleared when this exception is thrown.
       * @see    #notify()
       * @see    #notifyAll()
--- 385,22 ---
       * <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">
+      *          If this object is a {@linkplain Class#isValue() value object},
+      *          it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
+      *      </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 Class#isValue() value object}.
       * @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.
       * @see    #notify()
       * @see    #notifyAll()

*** 471,16 ***
       *         }
       *         ... // Perform action appropriate to condition or timeout
       *     }
       * }
       *
       * @param  timeoutMillis the maximum time to wait, in milliseconds
       * @param  nanos   additional time, in nanoseconds, in the range 0-999999 inclusive
       * @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
       * @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.
       * @see    #notify()
       * @see    #notifyAll()
--- 506,23 ---
       *         }
       *         ... // Perform action appropriate to condition or timeout
       *     }
       * }
       *
+      * <div class="preview-block">
+      *      <div class="preview-comment">
+      *          If this object is a {@linkplain Class#isValue() value object},
+      *          it does does not have a monitor, an {@code IllegalMonitorStateException} is thrown.
+      *      </div>
+      * </div>
       * @param  timeoutMillis the maximum time to wait, in milliseconds
       * @param  nanos   additional time, in nanoseconds, in the range 0-999999 inclusive
       * @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 Class#isValue() value object}.
       * @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.
       * @see    #notify()
       * @see    #notifyAll()