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

@@ -1,7 +1,7 @@
  /*
-  * Copyright (c) 1998, 2024, Oracle and/or its affiliates. All rights reserved.
+  * 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 +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}.