8388113: [lworld] JDI and JDWP spec update: ObjectReference summary, Value class clarification, strict field initialization clarification

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

@@ -1,5 +1,5 @@
 /*
- * 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
@@ -52,7 +52,20 @@
  * 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
@@ -87,6 +100,12 @@ public interface ObjectReference extends Value {
      * 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.
@@ -100,6 +119,12 @@ public interface ObjectReference extends Value {
      * 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.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, 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
@@ -519,7 +519,12 @@ default ModuleReference module() {
      * The Field must be valid for this type;
      * that is, it must be declared in this type, a superclass, a
      * superinterface, or an implemented interface.
-     *
+     * <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 field 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
@@ -533,6 +538,12 @@ default ModuleReference module() {
      * The Fields must be valid for this type;
      * that is, they must be declared in this type, a superclass, a
      * superinterface, or an implemented interface.
+     * <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.

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

@@ -97,10 +97,11 @@ public interface StackFrame extends Mirror, Locatable {
      * The {@link ObjectReference} for 'this' is only available for
      * non-native instance methods.
      * <p>
-     * If 'this' is a {@linkplain Class#isValue() value object} under
-     * construction, the returned {@code ObjectReference} will refer to a
-     * <em>snapshot</em> of the value object, not a reference to the actual value
-     * object under construction. Consequently, the returned
+     * If 'this' is a {@linkplain
+     * ObjectReference##valueObjects value object<sup class="preview-mark">PREVIEW</sup>}
+     * under construction, the returned {@code ObjectReference} will refer to a
+     * <em>snapshot</em> of the value object, not a reference
+     * to the actual value object under construction. Consequently, the returned
      * {@code ObjectReference} will not reflect changes to the value object that
      * happen later during construction.
      *

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2017, 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
@@ -31,6 +31,16 @@
  * The mirror for a value in the target VM.
  * This interface is the root of a
  * value hierarchy encompassing primitive values and object values.
+ * <div class="preview-block">
+ *      <div class="preview-comment">
+ * When preview features are enabled, JDI supports value classes. A "value class"
+ * as supported in the Java language is not related to the JDI Value interface.
+ * A "value class" is a class declared with the "value" modifier. The JDI
+ * Value interface is used by JDI to mirror a value in the debuggee VM. For more
+ * information on value classes, see Section {@jls value-objects-8.1.1.5 Value Classes}
+ * of <cite>The Java Language Specification</cite>.
+ *      </div>
+ * </div>
  * <P>
  * Some examples of where values may be accessed:
  * <BLOCKQUOTE><TABLE role="presentation">