8388113: [lworld] JDI and JDWP spec update: ObjectReference summary, Value class clarification, strict field initialization clarification by plummercj · Pull Request #2639 · openjdk/valhalla

plummercj · 2026-07-10T23:47:22Z

The following spec edits were made (no code changes):

a brief value object summary in the ObjectReference overview section
A clarification on the difference between "value classes/objects" and the JDI Value class
Specifying where JDI ignores strict field initialization rules.

The JBS issue contains screenshots of the rendered relevant javadoc.

I confirm that I make this contribution in accordance with the OpenJDK Interim AI Policy.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed (1 review required, with at least 1 Committer)

Issue

JDK-8388113: [lworld] JDI and JDWP spec update: ObjectReference summary, Value class clarification, strict field initialization clarification (Bug - P2)

Reviewers

Joe Darcy (@jddarcy - Committer) ⚠️ Review applies to 54eb553e
David Holmes (@dholmes-ora - Committer)
Serguei Spitsyn (@sspitsyn - Committer)
Dan Smith (@dansmithcode - Committer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/valhalla.git pull/2639/head:pull/2639
$ git checkout pull/2639

Update a local copy of the PR:
$ git checkout pull/2639
$ git pull https://git.openjdk.org/valhalla.git pull/2639/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 2639

View PR using the GUI difftool:
$ git pr show -t 2639

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/valhalla/pull/2639.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2026-07-10T23:48:33Z

👋 Welcome back cjplummer! A progress list of the required criteria for merging this PR into lworld will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2026-07-10T23:50:42Z

@plummercj This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

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

Reviewed-by: darcy, dholmes, sspitsyn, dlsmith

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 61 new commits pushed to the lworld branch:

db84603: 8388445: [lworld] update ProblemList-Xcomp.txt entries from 8378071 to 8388438
a1d8258: 8387875: [lworld] Provide value-class-preview.md file
53b4a9e: 8388261: [lworld] javac creates early_larval_frame and ACC_STRICT_INIT in record non-preview class files
... and 58 more: https://git.openjdk.org/valhalla/compare/23a199ffb1c27605257f1be6d8a5b8bcfa85e25d...lworld

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the lworld branch, type /integrate in a new comment.

mlbridge · 2026-07-11T01:16:51Z

Webrevs

JnRouvignac · 2026-07-11T07:16:29Z

+ * 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


"in particular"

Fixed. thank you.

dholmes-ora

If there is something special about the interaction of ObjectReferences and value objects then that should simply be stated at the appropriate location. This reads like a "what's new" section for value objects but I think it says far too much and is not something you would want to keep in this form once value objects are out of preview.

dholmes-ora · 2026-07-12T21:36:53Z

+ * 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


Suggested change

* to be immutable. Because of this, if 'this' is fetched from a value object

* to be immutable. Consequently, if 'this' is fetched from a value object

I assume this edit is no longer relevant after your earlier suggested rewrite of this section.

dholmes-ora · 2026-07-12T21:41:05Z

+ * <div class="preview-block">
+ *      <div class="preview-comment">
+ * <h2><a id=valueObjects>Value Objects</a></h2>
+ * When preview features are enabled, JDI supports value objects and classes


This whole paragraph seems excessive when there is nothing special to say about value objects here. You shouldn't have to say that JDI follows JLS and JVMS as that is a given, except where otherwise noted.

It's not a given. JDI does not implement the Java language nor a Java Virtual Machine, so it is not beholden to either spec. References to the JLS and JVMS (which already exist in the JDI javadoc) are used in places to aid in specifying JDI behavior.

Not sure what "beholden to the spec" actually means in this context, but to say JDI value object support is "consistent with JLS/JVMS" really doesn't tell you anything IMO. The main point here is simply that you can obtain an ObjectReference for a value object, just like any identity object. The only, very important, difference, is that it is a snapshot of the value object at that point in time. And whilst the value object is immutable, different ObjectReferences obtained during construction could capture different initalization states.

Your summary is correct. I was just trying to provide more context and understanding. I can take a stab at a more succinct version that makes no spec references.

...but keep in mind that I'm also trying to satisfy Joe's requests:

Additional comment: for JDI, I recommend including a short discussion of objects of value classes somewhere in the API; this would supplement the links to Class.isValue already in the patch.

And

my request is posed from the perspective of a reader of the JDI docs who is trying to find out how JDI works with respect to value classes. Value classes differ on == semantics, no locking, etc. So besides the point changes in various methods reflecting those updates, I think a brief paragraph (which could potentially be linked to from elsewhere in the JDI javadoc) explaining those points would be useful.

I don't want this to end up being reduced to just restating what is in StackFrame::thisObject(), which seems to be where your suggestions are headed.

I am somewhat at odds with Joe's requests. I understand where they are coming from but they are based on the "what's new" view of spec reading. When value objects are new it is understandable to ask "where are all the places where value objects need special handling". But to me that is where the JEP and/or release notes come into play. The spec's do not have these "what's new" sections. If they have overview sections then we can certainly add some mention of value objects (as done for JNI and JVMTI) but in minimal ways. Obviously it is necessary to explain what an ObjectReference means for a value object, but that is all that is needed within the ObjectReference spec.

dholmes-ora · 2026-07-12T21:41:50Z

+ * 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}).


Did you mean "two ObjectReferences are considered to be the same if ..." ?

I was referring to debuggee side value objects in this case. ObjectReferences are identity objects so two ObjectReferences are only "the same" if they are literally the same heap objects, just like with any other identity object. As noted below, ObjectReferences are considered to be equal (Object.equals()) if "==" of the target VM objects evaluates to true.

Then I don't understand the original sentence - it makes it sound like there are additional value objects. Did you just mean to state what the value object equality (edit: not identity) check is? i.e.

In particular, two value objects are considered to be the same if they are state-wise equivalent (x == y has the value true)

Yes, if by "identity" check you mean what is done for "==".

Sorry typo: s/identity/equality/

dholmes-ora · 2026-07-12T21:47:33Z

+ * {@jvms value-objects-6.5 if_acmp_cond} of the
+ * <cite>The Java Virtual Machine Specification</cite>.
+ * <p>
+ * Where JDI does differ from the JLS is in allowing the user to obtain an


I don't think this conversational style is suitable for this kind of API spec. The spec should just say what happens, not what it differs from. I would phrase more succinctly as:

If an ObjectReference is obtained for a value object under construction, then it is 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 the initial ObjectReference.

Ok. I'll work on this.

After re-reviewing you comments, it seem the only thing you really want in this section is to say "JDI supports value objects" and then mention the constructor warning you've written above. The latter isn't really adding any value since it is already explained in ObjectRefernece.thisObject(), so then this section boils down to "JDI supports value objects".

No, I want ObjectReference to explain how an ObjectReference that mirrors a value object differs from one that mirrors an identity object. If that duplicates what is said in StackFrame.thisObject() then maybe thisObject is not where it should be being described. Or maybe it is worth noting in both places. But it certainly has to be noted in ObjectReference IMO.

dholmes-ora

This all seems fine to me. Thanks

sspitsyn

This looks good.

plummercj

Thank you everyone for the reviews!

/integrate

openjdk · 2026-07-17T21:15:58Z

Going to push as commit a0662f9.
Since your change was applied there have been 61 commits pushed to the lworld branch:

db84603: 8388445: [lworld] update ProblemList-Xcomp.txt entries from 8378071 to 8388438
a1d8258: 8387875: [lworld] Provide value-class-preview.md file
53b4a9e: 8388261: [lworld] javac creates early_larval_frame and ACC_STRICT_INIT in record non-preview class files
... and 58 more: https://git.openjdk.org/valhalla/compare/23a199ffb1c27605257f1be6d8a5b8bcfa85e25d...lworld

Your commit was automatically rebased without conflicts.

openjdk · 2026-07-17T21:16:09Z

@plummercj Pushed as commit a0662f9.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

AlanBateman · 2026-07-20T10:29:45Z

I see this has already been integrated but it is problematic to use "If preview features are enabled" in the JDI spec without clarifying that it means preview features in the target VM are enabled. Whether preview features are enabled or not in the current VM is not really relevant. It gets more complicated when the JDK version used for the front-end (JDI) is different to the JDK version in the back-end (target VM), and more complicated again once JDI is "upgraded" or copied into the JDK used by the IDE/debugger.

It's a similar discussion to that in JDK-8387726 which is why we decided that the simplest is for StackFrame.thisObject to link to Class.isValue instead of "If preview features are enabled".

addtional javadoc content for value objects

4356b64

openjdk Bot changed the title ~~8388113~~ 8388113: [lworld] Add summary of JDI support for value objects in ObjectReference javadoc Jul 10, 2026

plummercj added 2 commits July 10, 2026 17:06

fix copyright

54eb553

fix whitespace

beca530

jddarcy approved these changes Jul 11, 2026

View reviewed changes

openjdk Bot added ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jul 11, 2026

JnRouvignac reviewed Jul 11, 2026

View reviewed changes

fix comment typo

adae0f5

dholmes-ora reviewed Jul 12, 2026

View reviewed changes

plummercj changed the title ~~8388113: [lworld] Add summary of JDI support for value objects in ObjectReference javadoc~~ 8388113: [lworld] JDI and JDWP spec update: ObjectReference summary, Value class clarification, strict field initialization clarification Jul 17, 2026

plummercj added 2 commits July 16, 2026 17:17

major rework

9b8c739

fix minor typo

2c16e8e

dholmes-ora approved these changes Jul 17, 2026

View reviewed changes

Value is an interface, not a class

2094284

dholmes-ora approved these changes Jul 17, 2026

View reviewed changes

sspitsyn approved these changes Jul 17, 2026

View reviewed changes

dansmithcode approved these changes Jul 17, 2026

View reviewed changes

plummercj commented Jul 17, 2026

View reviewed changes

openjdk Bot added the integrated Pull request has been integrated label Jul 17, 2026

openjdk Bot closed this Jul 17, 2026

openjdk Bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jul 17, 2026

	* to be immutable. Because of this, if 'this' is fetched from a value object
	* to be immutable. Consequently, if 'this' is fetched from a value object

		* 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}).

Uh oh!

Conversation

plummercj commented Jul 10, 2026 • edited by openjdk Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper Bot commented Jul 10, 2026

Uh oh!

openjdk Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mlbridge Bot commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dholmes-ora left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dholmes-ora Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

plummercj Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dholmes-ora left a comment

Choose a reason for hiding this comment

Uh oh!

sspitsyn left a comment

Choose a reason for hiding this comment

Uh oh!

plummercj left a comment

Choose a reason for hiding this comment

Uh oh!

openjdk Bot commented Jul 17, 2026

Uh oh!

openjdk Bot commented Jul 17, 2026

Uh oh!

AlanBateman commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

plummercj commented Jul 10, 2026 •

edited by openjdk Bot

Loading

openjdk Bot commented Jul 10, 2026 •

edited

Loading

mlbridge Bot commented Jul 11, 2026 •

edited

Loading

dholmes-ora Jul 13, 2026 •

edited

Loading

plummercj Jul 13, 2026 •

edited

Loading