From 4356b6456f648133cfaf68a83f108888c5a6b506 Mon Sep 17 00:00:00 2001 From: Chris Plummer Date: Fri, 10 Jul 2026 16:41:08 -0700 Subject: [PATCH 1/7] addtional javadoc content for value objects --- .../classes/com/sun/jdi/ObjectReference.java | 31 ++++++++++++++++++- .../share/classes/com/sun/jdi/StackFrame.java | 9 +++--- 2 files changed, 35 insertions(+), 5 deletions(-) diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java index f53b8acbb8b..2c29b6ca66f 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java +++ b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java @@ -52,7 +52,36 @@ * takes ObjectReference as parameter may throw * {@link ObjectCollectedException} if the mirrored object has been * garbage collected. - * + *
+ *
+ *

Value Objects

+ * When preview features are enabled, JDI supports value objects and classes + * in a manner consistent with The Java Language Specification and + * The Java Virtual Machine Specification, with one exception noted + * below. In particular, two value objects are considered to be the same if both + * refer to statewise-equivalent value objects (x == y has the value {@code true}). + * {@link ObjectReference#equals} has always been defined to return true if + * applying the "==" operator on the mirrored objects in the target VM + * evaluates to true. That has not changed with value objects. See Sections + * {@jls value-objects-8.1.1.5 Value Classes} and + * {@jls value-objects-15.21.3 Object Equality Operators} of + * The Java Language Specification, and Section + * {@jvms value-objects-6.5 if_acmp_cond} of the + * The Java Virtual Machine Specification. + *

+ * Where JDI does differ from the JLS is in allowing the user to obtain an + * ObjectReference to a value object under construction (while in the "larval" + * state). For example, the JDI user could fetch 'this' after hitting a + * breakpoint in the value object contructor. This could lead to confusing + * behavior for the JDI user. In particlar, the value object may change after + * the ObjectReference is obtained, even though value objects are considered + * to be immutable. Because of this, if 'this' is fetched from a value object + * constructor, an ObjectReference representing a statewise-equivalent "snapshot" + * is returned instead, and this ObjectReference will not reflect changes to the + * value object that happen later during construction. See + * {@link StackFrame#thisObject}. + *

+ *
* @author Robert Field * @author Gordon Hirsch * @author James McIlree diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/StackFrame.java b/src/jdk.jdi/share/classes/com/sun/jdi/StackFrame.java index 2a0b1718f31..579419acfde 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/StackFrame.java +++ b/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. *

- * If 'this' is a {@linkplain Class#isValue() value object} under - * construction, the returned {@code ObjectReference} will refer to a - * snapshot 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 objectPREVIEW} + * under construction, the returned {@code ObjectReference} will refer to a + * statewise-equivalent snapshot 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. * From 54eb553e0747ba9f7571fac02aa69c1760302514 Mon Sep 17 00:00:00 2001 From: Chris Plummer Date: Fri, 10 Jul 2026 17:06:05 -0700 Subject: [PATCH 2/7] fix copyright --- src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java index 2c29b6ca66f..2f6fd201eef 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java +++ b/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 From beca530a25c2a1436d302441d00dd218a0ee56ba Mon Sep 17 00:00:00 2001 From: Chris Plummer Date: Fri, 10 Jul 2026 17:33:27 -0700 Subject: [PATCH 3/7] fix whitespace --- src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java index 2f6fd201eef..2e91d8efad0 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java +++ b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java @@ -65,7 +65,7 @@ * evaluates to true. That has not changed with value objects. See Sections * {@jls value-objects-8.1.1.5 Value Classes} and * {@jls value-objects-15.21.3 Object Equality Operators} of - * The Java Language Specification, and Section + * The Java Language Specification, and Section * {@jvms value-objects-6.5 if_acmp_cond} of the * The Java Virtual Machine Specification. *

From adae0f546e53255cec44c85dd4c62ee63707621d Mon Sep 17 00:00:00 2001 From: Chris Plummer Date: Sat, 11 Jul 2026 12:32:48 -0700 Subject: [PATCH 4/7] fix comment typo --- src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java index 2e91d8efad0..f6c74f69d58 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java +++ b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java @@ -73,7 +73,7 @@ * ObjectReference to a value object under construction (while in the "larval" * state). For example, the JDI user could fetch 'this' after hitting a * breakpoint in the value object contructor. This could lead to confusing - * behavior for the JDI user. In particlar, the value object may change after + * behavior for the JDI user. In particular, the value object may change after * the ObjectReference is obtained, even though value objects are considered * to be immutable. Because of this, if 'this' is fetched from a value object * constructor, an ObjectReference representing a statewise-equivalent "snapshot" From 9b8c739ddb17c436ec6a38fc5704aad717d68d41 Mon Sep 17 00:00:00 2001 From: Chris Plummer Date: Thu, 16 Jul 2026 17:17:58 -0700 Subject: [PATCH 5/7] major rework --- .../classes/com/sun/jdi/ObjectReference.java | 44 +++++++++---------- .../classes/com/sun/jdi/ReferenceType.java | 15 ++++++- .../share/classes/com/sun/jdi/StackFrame.java | 2 +- .../share/classes/com/sun/jdi/Value.java | 12 ++++- 4 files changed, 45 insertions(+), 28 deletions(-) diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java index f6c74f69d58..eb6bae48ef1 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java +++ b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java @@ -55,31 +55,15 @@ *

*
*

Value Objects

- * When preview features are enabled, JDI supports value objects and classes - * in a manner consistent with The Java Language Specification and - * The Java Virtual Machine Specification, with one exception noted - * below. In particular, two value objects are considered to be the same if both - * refer to statewise-equivalent value objects (x == y has the value {@code true}). - * {@link ObjectReference#equals} has always been defined to return true if - * applying the "==" operator on the mirrored objects in the target VM - * evaluates to true. That has not changed with value objects. See Sections - * {@jls value-objects-8.1.1.5 Value Classes} and - * {@jls value-objects-15.21.3 Object Equality Operators} of - * The Java Language Specification, and Section - * {@jvms value-objects-6.5 if_acmp_cond} of the - * The Java Virtual Machine Specification. + *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: *

- * Where JDI does differ from the JLS is in allowing the user to obtain an - * ObjectReference to a value object under construction (while in the "larval" - * state). For example, the JDI user could fetch 'this' after hitting a - * breakpoint in the value object contructor. This could lead to confusing - * behavior for the JDI user. In particular, the value object may change after - * the ObjectReference is obtained, even though value objects are considered - * to be immutable. Because of this, if 'this' is fetched from a value object - * constructor, an ObjectReference representing a statewise-equivalent "snapshot" - * is returned instead, and this ObjectReference will not reflect changes to the - * value object that happen later during construction. See - * {@link StackFrame#thisObject}. + * If an ObjectReference is obtained for a value object under construction, + * it will be for a snapshot 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}. *

*
* @author Robert Field @@ -116,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. + *
+ *
+ * If preview features are enabled, this method does not prevent a + * strictly-initialized field from being read before it has been initialized. + *
+ *
* * @param sig the field containing the requested value * @return the {@link Value} of the instance field. @@ -129,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. + *
+ *
+ * If preview features are enabled, this method does not prevent a + * strictly-initialized field from being read before it has been initialized. + *
+ *
* * @param fields a list of {@link Field} objects containing the * requested values. diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ReferenceType.java b/src/jdk.jdi/share/classes/com/sun/jdi/ReferenceType.java index 043acc839f7..66664db999d 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/ReferenceType.java +++ b/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. - * + *
+ *
+ * If preview features are enabled, this method does not prevent a + * strictly-initialized field from being read before it has been initialized. + *
+ *
* @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. + *
+ *
+ * If preview features are enabled, this method does not prevent a + * strictly-initialized field from being read before it has been initialized. + *
+ *
* * @param fields a list of {@link Field} objects containing the * requested values. diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/StackFrame.java b/src/jdk.jdi/share/classes/com/sun/jdi/StackFrame.java index 579419acfde..570a167038c 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/StackFrame.java +++ b/src/jdk.jdi/share/classes/com/sun/jdi/StackFrame.java @@ -100,7 +100,7 @@ public interface StackFrame extends Mirror, Locatable { * If 'this' is a {@linkplain * ObjectReference##valueObjects value objectPREVIEW} * under construction, the returned {@code ObjectReference} will refer to a - * statewise-equivalent snapshot of the value object, not a reference + * snapshot 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. diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/Value.java b/src/jdk.jdi/share/classes/com/sun/jdi/Value.java index 42afbc2bfdf..cffac649d58 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/Value.java +++ b/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. + *
+ *
+ * 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 class. + * A "value class" is a class declared with the "value" modifier. The JDI + * Value class 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 The Java Language Specification. + *
+ *
*

* Some examples of where values may be accessed: *

From 2c16e8e697da31ceb4607a9c80c220c901b12958 Mon Sep 17 00:00:00 2001 From: Chris Plummer Date: Thu, 16 Jul 2026 17:19:40 -0700 Subject: [PATCH 6/7] fix minor typo --- src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java index eb6bae48ef1..33ea1b7ae1f 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java +++ b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java @@ -55,7 +55,7 @@ *
*
*

Value Objects

- *If preview features are enabled, JDI supports value objects and classes. + * 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: *

From 2094284eeca41fd01c12e2587fd2666f5c89dc6d Mon Sep 17 00:00:00 2001 From: Chris Plummer Date: Thu, 16 Jul 2026 19:30:34 -0700 Subject: [PATCH 7/7] Value is an interface, not a class --- src/jdk.jdi/share/classes/com/sun/jdi/Value.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/Value.java b/src/jdk.jdi/share/classes/com/sun/jdi/Value.java index cffac649d58..19a0c98d169 100644 --- a/src/jdk.jdi/share/classes/com/sun/jdi/Value.java +++ b/src/jdk.jdi/share/classes/com/sun/jdi/Value.java @@ -34,9 +34,9 @@ *

*
* 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 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 class is used by JDI to mirror a value in the debuggee VM. For more + * 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 The Java Language Specification. *