From 69b06d4bcf60c007f75074bc79a390922fb34886 Mon Sep 17 00:00:00 2001 From: Volker Simonis Date: Wed, 3 Jul 2024 18:08:29 +0200 Subject: [PATCH 1/4] 8335619: Add an @apiNote to j.l.i.ClassFileTransformer to warn about recursive class loading and ClassCircularityErrors --- .../java/lang/instrument/ClassFileTransformer.java | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java b/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java index d4c17f1cfdcf7..e888b494a6545 100644 --- a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java +++ b/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java @@ -160,6 +160,20 @@ * sequence of bytes in class file format, whether or not they reside in a * file. * + * @apiNote + * If the invocation of {@link #transform transform()} for a class C + * directly or transitively requires loading or resolving the same class C, + * an error is thrown that is an instance of {@link LinkageError} (or a subclass). + * Transforming core JDK classes or using libraries which depend on core JDK classes + * during transformation increases the risk for such errors. If the {@link LinkageError} + * occurs during reference resolution (see section 5.4.3 Resolution of The + * Java Virtual Machine Specification) for a class D, the + * corresponding reference resolution in class D will always fail + * with the same error. This means that a {@link LinkageError} triggered during + * transformation of C in a class D not directly related to + * C can repeatedly occur later in arbitrary user code which uses class + * D. + * * @see java.lang.instrument.Instrumentation * @since 1.5 */ From 080999e1b2e5305228ad85383aba8584271413a0 Mon Sep 17 00:00:00 2001 From: Volker Simonis Date: Thu, 4 Jul 2024 12:43:13 +0200 Subject: [PATCH 2/4] Fixed text based on reviewer comments. Also added a '@jvms' tag to another reference to the JVMS and fixed its section number --- .../lang/instrument/ClassFileTransformer.java | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java b/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java index e888b494a6545..57ed438c6c514 100644 --- a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java +++ b/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java @@ -155,24 +155,24 @@ * logging or debugging of format corruptions. * *

- * Note the term class file is used as defined in section 3.1 of + * Note the term class file is used as defined in section {@jvms 4} of * The Java Virtual Machine Specification, to mean a * sequence of bytes in class file format, whether or not they reside in a * file. * * @apiNote - * If the invocation of {@link #transform transform()} for a class C - * directly or transitively requires loading or resolving the same class C, + * If the invocation of {@link #transform transform()} for a class {@code C} + * directly or transitively requires loading or resolving the same class {@code C}, * an error is thrown that is an instance of {@link LinkageError} (or a subclass). - * Transforming core JDK classes or using libraries which depend on core JDK classes - * during transformation increases the risk for such errors. If the {@link LinkageError} - * occurs during reference resolution (see section 5.4.3 Resolution of The - * Java Virtual Machine Specification) for a class D, the - * corresponding reference resolution in class D will always fail + * Transforming core JDK classes or using libraries that depend on core JDK classes + * during transformation increases the risk of such errors. If the {@link LinkageError} + * occurs during reference resolution (see section {@jvms 5.4.3} Resolution of The + * Java Virtual Machine Specification) for a class {@code D}, the + * corresponding reference resolution in class {@code D} will always fail * with the same error. This means that a {@link LinkageError} triggered during - * transformation of C in a class D not directly related to - * C can repeatedly occur later in arbitrary user code which uses class - * D. + * 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 class + * {@code D}. * * @see java.lang.instrument.Instrumentation * @since 1.5 From 5fb8553322881378567702f9efd740a91d8ced57 Mon Sep 17 00:00:00 2001 From: Volker Simonis Date: Tue, 9 Jul 2024 16:10:01 +0200 Subject: [PATCH 3/4] Addressed @AlanBateman's suggestions and updated copyright year --- .../lang/instrument/ClassFileTransformer.java | 34 +++++++++++-------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java b/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java index 57ed438c6c514..d06a4bae91efa 100644 --- a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java +++ b/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,24 +155,28 @@ * logging or debugging of format corruptions. * *

- * Note the term class file is used as defined in section {@jvms 4} of - * The Java Virtual Machine Specification, to mean a - * sequence of bytes in class file format, whether or not they reside in a + * Note the term class file is used as defined in section {@jvms 4} The + * {@code class} File Format of The Java Virtual Machine Specification, + * to mean a sequence of bytes in class file format, whether or not they reside in a * file. * * @apiNote - * If the invocation of {@link #transform transform()} for a class {@code C} - * directly or transitively requires loading or resolving the same class {@code C}, + * 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. Using bytecode transformation libraries which depend + * on core JDK class can increase the risk of such errors. + * + *

+ * 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). - * Transforming core JDK classes or using libraries that depend on core JDK classes - * during transformation increases the risk of such errors. If the {@link LinkageError} - * occurs during reference resolution (see section {@jvms 5.4.3} Resolution of The - * Java Virtual Machine Specification) for a class {@code D}, the - * corresponding reference resolution in class {@code D} will always fail - * with the same error. 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 class - * {@code D}. + * If the {@link LinkageError} occurs during reference resolution (see section + * {@jvms 5.4.3} Resolution of The Java Virtual Machine Specification) + * 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 From f8429bc479e9c1fdc9dc1b6535d396ae0829a050 Mon Sep 17 00:00:00 2001 From: Volker Simonis Date: Wed, 10 Jul 2024 18:57:41 +0200 Subject: [PATCH 4/4] Addressed @AlanBateman's new suggestions --- .../classes/java/lang/instrument/ClassFileTransformer.java | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java b/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java index d06a4bae91efa..ee2037fac5bfb 100644 --- a/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java +++ b/src/java.instrument/share/classes/java/lang/instrument/ClassFileTransformer.java @@ -155,7 +155,7 @@ * logging or debugging of format corruptions. * *

- * Note the term class file is used as defined in section {@jvms 4} The + * Note the term class file is used as defined in chapter {@jvms 4} The * {@code class} File Format of The Java Virtual Machine Specification, * to mean a sequence of bytes in class file format, whether or not they reside in a * file. @@ -163,8 +163,7 @@ * @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. Using bytecode transformation libraries which depend - * on core JDK class can increase the risk of such errors. + * circularity or linkage errors. * *

* If for example the invocation of {@link #transform transform()} for a class