src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java

*** 1,7 ***
  /*
!  * Copyright (c) 1998, 2024, 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
--- 1,7 ---
  /*
!  * Copyright (c) 1998, 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

*** 50,11 ***
   * <p>
   * Any method on <code>ObjectReference</code> or which directly or indirectly
   * takes <code>ObjectReference</code> as parameter may throw
   * {@link ObjectCollectedException} if the mirrored object has been
   * garbage collected.
!  *
   * @author Robert Field
   * @author Gordon Hirsch
   * @author James McIlree
   * @since  1.3
   */
--- 50,24 ---
   * <p>
   * Any method on <code>ObjectReference</code> or which directly or indirectly
   * takes <code>ObjectReference</code> as parameter may throw
   * {@link ObjectCollectedException} if the mirrored object has been
   * garbage collected.
!  * <div class="preview-block">
+  *      <div class="preview-comment">
+  * <h2><a id=valueObjects>Value Objects</a></h2>
+  * If preview features are enabled, JDI supports value objects and classes.
+  * However, the support does in some cases deviate from identity object
+  * support in behavior or expectations as noted below:
+  * <p>
+  * If an ObjectReference is obtained for a value object under construction,
+  * it will be for a <em>snapshot</em> of the value object at that point in time.
+  * Any further changes to the initialization state of the value object will not
+  * be reflected in this ObjectReference. A new ObjectReference would need to
+  * be obtained to see the updated state. See {@link StackFrame#thisObject}.
+  *      </div>
+  * </div>
   * @author Robert Field
   * @author Gordon Hirsch
   * @author James McIlree
   * @since  1.3
   */

*** 85,10 ***
--- 98,16 ---
      /**
       * Gets the value of a given instance or static field in this object.
       * The Field must be valid for this ObjectReference;
       * that is, it must be from
       * the mirrored object's class or a superclass of that class.
+      * <div class="preview-block">
+      *      <div class="preview-comment">
+      * If preview features are enabled, this method does not prevent a
+      * strictly-initialized field from being read before it has been initialized.
+      *      </div>
+      * </div>
       *
       * @param sig the field containing the requested value
       * @return the {@link Value} of the instance field.
       * @throws java.lang.IllegalArgumentException if the field is not valid for
       * this object's class.

*** 98,10 ***
--- 117,16 ---
      /**
       * Gets the value of multiple instance and/or static fields in this object.
       * The Fields must be valid for this ObjectReference;
       * that is, they must be from
       * the mirrored object's class or a superclass of that class.
+      * <div class="preview-block">
+      *      <div class="preview-comment">
+      * If preview features are enabled, this method does not prevent a
+      * strictly-initialized field from being read before it has been initialized.
+      *      </div>
+      * </div>
       *
       * @param fields a list of {@link Field} objects containing the
       * requested values.
       * @return a Map of the requested {@link Field} objects with
       * their {@link Value}.