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.