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

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

*** 95,10 ***
--- 95,23 ---
      /**
       * Returns the value of 'this' for the current frame.
       * The {@link ObjectReference} for 'this' is only available for
       * non-native instance methods.
       *
+      * @apiNote
+      * <div class="preview-block">
+      *     <div class="preview-comment">
+      *         When preview features are enabled,
+      *         if 'this' represents a value object under construction, the
+      *         {@link ObjectReference} returned will be for a snapshot of the
+      *         value object, not a reference to the actual value object under
+      *         construction. Therefore the ObjectReference returned will not reflect
+      *         changes to the value object that happen later on during
+      *         construction.
+      *     </div>
+      * </div>
+      *
       * @return an {@link ObjectReference}, or null if the frame represents
       * a native or static method.
       * @throws InvalidStackFrameException if this stack frame has become
       * invalid. Once the frame's thread is resumed, the stack frame is
       * no longer valid.

*** 166,10 ***
--- 179,24 ---
      /**
       * Gets the {@link Value} of a {@link LocalVariable} in this frame.
       * The variable must be valid for this frame's method and visible
       * according to the rules described in {@link #visibleVariables}.
       *
+      * @apiNote
+      * <div class="preview-block">
+      *     <div class="preview-comment">
+      *         When preview features are enabled,
+      *         if the variable represents `this` of a value object that
+      *         is under construction, the
+      *         {@link ObjectReference} returned will be for a snapshot of the
+      *         value object, not a reference to the actual value object under
+      *         construction. Therefore the {@link ObjectReference} returned will not reflect
+      *         changes to the value object that happen later on during
+      *         construction.
+      *     </div>
+      * </div>
+      *
       * @param variable the {@link LocalVariable} to be accessed
       * @return the {@link Value} of the instance field.
       * @throws java.lang.IllegalArgumentException if the variable is
       * either invalid for this frame's method or not visible.
       * @throws InvalidStackFrameException if this stack frame has become

*** 181,10 ***
--- 208,24 ---
      /**
       * Returns the values of multiple local variables in this frame.
       * Each variable must be valid for this frame's method and visible
       * according to the rules described in {@link #visibleVariables}.
       *
+      * @apiNote
+      * <div class="preview-block">
+      *     <div class="preview-comment">
+      *         When preview features are enabled,
+      *         if a variable represents `this` of a value object that
+      *         is under construction, the
+      *         {@link ObjectReference} returned will be for a snapshot of the
+      *         value object, not a reference to the actual value object under
+      *         construction. Therefore the {@link ObjectReference} returned will not reflect
+      *         changes to the value object that happen later on during
+                construction.
+      *      </div>
+      * </div>
+      *
       * @param variables a list of {@link LocalVariable} objects to be accessed
       * @return a map associating each {@link LocalVariable} with
       * its {@link Value}
       * @throws java.lang.IllegalArgumentException if any variable is
       * either invalid for this frame's method or not visible.