8335619: Add an @apiNote to j.l.i.ClassFileTransformer to warn about recursive class loading and ClassCircularityErrors

[fandreuz]

Almost clean backport of JDK-8335619, except for a conflict in the copyright header (year). Adds useful information for users of java.lang.instrument.

---

Progress

• Change must not contain extraneous whitespace
• JDK-8335619 needs maintainer approval
• Commit message must refer to an issue

Issue

• JDK-8335619: Add an @apiNote to j.l.i.ClassFileTransformer to warn about recursive class loading and ClassCircularityErrors (Enhancement - P4)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk21u-dev.git pull/2012/head:pull/2012
$ git checkout pull/2012

Update a local copy of the PR:
$ git checkout pull/2012
$ git pull https://git.openjdk.org/jdk21u-dev.git pull/2012/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 2012

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk21u-dev/pull/2012.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

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

[openjdk]

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

[openjdk]

This backport pull request has now been updated with issue from the original commit.

[openjdk]

⚠️ @fandreuz This change is now ready for you to apply for maintainer approval. This can be done directly in each associated issue or by using the /approval command.

[mlbridge]

Webrevs

• 00: Full (f2809f8c)

[fandreuz]

/approval request Fixes JDK-8335619. Adds useful information about potential issues for users of java.lang.instrument. Almost clean except for a conflict in the license header.

[openjdk]

@fandreuz
8335619: The approval request has been created successfully.

[GoeLin]

Hi @fandreuz,
this change might need a CSR if backported, or even a change of the standard. Can you please check
with Joe Darcy that it is fine to backport this as-is?
I'll remove the label in the meantime.

[simonis]

HI @GoeLin,

I don't think this backport requires a CSR. I've evaluated the need for a CSR in the initial PR and came to the conclusion (together with the reviewers) that it is not needed because:

Notice that according to the CSR FAQ, I don't think that this change requires a CSR because it is not changing the specification but merely describes the actual behavior in some more detail:

Q: If the text of the javadoc of a public exported API is changing, is a CSR request needed?
A: A CSR request is required if the specification of a public exported API. Not all javadoc updates are specification changes. For example, typo fixes and rephrasings that do not alter the semantics of the API in question do not require CSR review.

Also, the @apiNote is a non standard (i.e. JDK-scope and not SE-scope tag, see JDK-8068562: javadoc tags to distinguish API, implementation, specification, and notes), so again, because this is not specification relevant, I think no CSR is needed for the backport.

[fandreuz]

Hi @GoeLin, does the comment by @simonis answers your question? Let me know if I should check with Joe Darcy anyway.

[bridgekeeper]

@fandreuz This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply issue a /touch or /keepalive command to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[Cirocc]

Although this issue manifests primarily when using Project Loom (Virtual Threads), that makes it even more critical. Loom is the flagship feature of JDK 21 and the main reason many enterprises are adopting this LTS release.

With this bug, major instrumentation tools (AppDynamics, DataDog, New Relic, etc.) cannot function correctly on JDK 21 with Loom, effectively blocking safe adoption of one of the most important features in modern Java.

I strongly urge the maintainers to prioritize the integration of this backport into 21u, as it is a blocker for enterprise production environments that depend on monitoring and observability.

[simonis]

Although this issue manifests primarily when using Project Loom (Virtual Threads), that makes it even more critical. Loom is the flagship feature of JDK 21 and the main reason many enterprises are adopting this LTS release.

With this bug, major instrumentation tools (AppDynamics, DataDog, New Relic, etc.) cannot function correctly on JDK 21 with Loom, effectively blocking safe adoption of one of the most important features in modern Java.

I strongly urge the maintainers to prioritize the integration of this backport into 21u, as it is a blocker for enterprise production environments that depend on monitoring and observability.

@Cirocc, I don't understand your comment. While I agree that this change should be downported, I don't understand how it can "unblock" monitoring/instrumentation tools because this PR only adds an API note to the documentation.

[bridgekeeper]

@fandreuz This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply issue a /touch or /keepalive command to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[bridgekeeper]

@fandreuz This pull request has been inactive for more than 8 weeks and will now be automatically closed. If you would like to continue working on this pull request in the future, feel free to reopen it! This can be done using the /open pull request command.