stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Reviewed-by: alanb, stuefe, liach
This commit is contained in:
Volker Simonis 2024-07-12 12:09:58 +00:00
parent 9b6f6c5c9d
commit eec0e155f3
1 changed files with 21 additions and 4 deletions

25
src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2023, 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
@ -155,11 +155,28 @@ import java.security.ProtectionDomain;
* 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
*/