Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 21 additions & 4 deletions src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2024, 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
Expand Down Expand Up @@ -155,11 +155,28 @@
* logging or debugging of format corruptions.
*
* <P>
* Note the term <i>class file</i> is used as defined in section 3.1 of
* <cite>The Java Virtual Machine Specification</cite>, to mean a
* sequence of bytes in class file format, whether or not they reside in a
* Note the term <i>class file</i> is used as defined in chapter {@jvms 4} The
* {@code class} File Format of <cite>The Java Virtual Machine Specification</cite>,
* to mean a sequence of bytes in class file format, whether or not they reside in a
* file.
*
* @apiNote
* Great care must be taken when transforming core JDK classes which are at the
* same time required during the transformation process as this can lead to class
* circularity or linkage errors.
*
* <P>
* If for example the invocation of {@link #transform transform()} for a class
* {@code C} requires loading or resolving the same class {@code C},
* an error is thrown that is an instance of {@link LinkageError} (or a subclass).
* If the {@link LinkageError} occurs during reference resolution (see section
* {@jvms 5.4.3} Resolution of <cite>The Java Virtual Machine Specification</cite>)
* for a class {@code D}, the resolution of the corresponding reference in class
* {@code D} will permanently fail with the same error at any subsequent attempt.
* This means that a {@link LinkageError} triggered during transformation of
* {@code C} in a class {@code D} not directly related to {@code C} can repeatedly
* occur later in arbitrary user code which uses {@code D}.
*
* @see java.lang.instrument.Instrumentation
* @since 1.5
*/
Expand Down