1 /*
2 * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.instrument;
27
28 import java.security.ProtectionDomain;
29
30 /*
31 * Copyright 2003 Wily Technology, Inc.
32 */
33
34 /**
35 * A transformer of class files. An agent registers an implementation of this
36 * interface using the {@link Instrumentation#addTransformer addTransformer}
37 * method so that the transformer's {@link
38 * ClassFileTransformer#transform(Module,ClassLoader,String,Class,ProtectionDomain,byte[])
39 * transform} method is invoked when classes are loaded,
40 * {@link Instrumentation#redefineClasses redefined}, or
41 * {@link Instrumentation#retransformClasses retransformed}. The implementation
42 * should override one of the {@code transform} methods defined here.
43 * Transformers are invoked before the class is defined by the Java virtual
44 * machine.
45 *
46 * <P>
47 * There are two kinds of transformers, determined by the <code>canRetransform</code>
48 * parameter of
49 * {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer,boolean)}:
50 * <ul>
51 * <li><i>retransformation capable</i> transformers that were added with
52 * <code>canRetransform</code> as true
53 * </li>
54 * <li><i>retransformation incapable</i> transformers that were added with
55 * <code>canRetransform</code> as false or where added with
56 * {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer)}
57 * </li>
58 * </ul>
59 *
60 * <P>
61 * Once a transformer has been registered with
62 * {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer,boolean)
63 * addTransformer},
64 * the transformer will be called for every new class definition and every class redefinition.
65 * Retransformation capable transformers will also be called on every class retransformation.
66 * The request for a new class definition is made with
67 * {@link java.lang.ClassLoader#defineClass ClassLoader.defineClass}
68 * or its native equivalents.
69 * The request for a class redefinition is made with
70 * {@link java.lang.instrument.Instrumentation#redefineClasses Instrumentation.redefineClasses}
71 * or its native equivalents.
72 * The request for a class retransformation is made with
73 * {@link java.lang.instrument.Instrumentation#retransformClasses Instrumentation.retransformClasses}
74 * or its native equivalents.
75 * The transformer is called during the processing of the request, before the class file bytes
76 * have been verified or applied.
77 * When there are multiple transformers, transformations are composed by chaining the
78 * <code>transform</code> calls.
79 * That is, the byte array returned by one call to <code>transform</code> becomes the input
80 * (via the <code>classfileBuffer</code> parameter) to the next call.
81 *
82 * <P>
83 * Transformations are applied in the following order:
84 * <ul>
85 * <li>Retransformation incapable transformers
86 * </li>
87 * <li>Retransformation incapable native transformers
88 * </li>
89 * <li>Retransformation capable transformers
90 * </li>
91 * <li>Retransformation capable native transformers
92 * </li>
93 * </ul>
94 *
95 * <P>
96 * For retransformations, the retransformation incapable transformers are not
97 * called, instead the result of the previous transformation is reused.
98 * In all other cases, this method is called.
99 * Within each of these groupings, transformers are called in the order registered.
100 * Native transformers are provided by the <code>ClassFileLoadHook</code> event
101 * in the Java Virtual Machine Tool Interface).
102 *
103 * <P>
104 * The input (via the <code>classfileBuffer</code> parameter) to the first
105 * transformer is:
106 * <ul>
107 * <li>for new class definition,
108 * the bytes passed to <code>ClassLoader.defineClass</code>
109 * </li>
110 * <li>for class redefinition,
111 * <code>definitions.getDefinitionClassFile()</code> where
112 * <code>definitions</code> is the parameter to
113 * {@link java.lang.instrument.Instrumentation#redefineClasses
114 * Instrumentation.redefineClasses}
115 * </li>
116 * <li>for class retransformation,
117 * the bytes passed to the new class definition or, if redefined,
118 * the last redefinition, with all transformations made by retransformation
119 * incapable transformers reapplied automatically and unaltered;
120 * for details see
121 * {@link java.lang.instrument.Instrumentation#retransformClasses
122 * Instrumentation.retransformClasses}
123 * </li>
124 * </ul>
125 *
126 * <P>
127 * If the implementing method determines that no transformations are needed,
128 * it should return <code>null</code>.
129 * Otherwise, it should create a new <code>byte[]</code> array,
130 * copy the input <code>classfileBuffer</code> into it,
131 * along with all desired transformations, and return the new array.
132 * The input <code>classfileBuffer</code> must not be modified.
133 *
134 * <P>
135 * In the retransform and redefine cases,
136 * the transformer must support the redefinition semantics:
137 * if a class that the transformer changed during initial definition is later
138 * retransformed or redefined, the
139 * transformer must insure that the second class output class file is a legal
140 * redefinition of the first output class file.
141 *
142 * <P>
143 * The transformers can define additional classes when a class is
144 * being transformed via {@link ClassDefiner#defineClass(byte[])
145 * ClassDefiner.defineClass}. They will be defined to the same class loader and
146 * the same protection domain as the class being transformed.
147 *
148 * <P>
149 * If the transformer throws an exception (which it doesn't catch),
150 * subsequent transformers will still be called and the load, redefine
151 * or retransform will still be attempted.
152 * Thus, throwing an exception has the same effect as returning {@code null}.
153 * To prevent unexpected behavior when unchecked exceptions are generated
154 * in transformer code, a transformer can catch <code>Throwable</code>.
155 * If the transformer believes the <code>classFileBuffer</code> does not
156 * represent a validly formatted class file, it should throw
157 * an <code>IllegalClassFormatException</code>;
158 * while this has the same effect as returning {@code null}, it facilitates the
159 * logging or debugging of format corruptions.
160 *
161 * <P>
162 * Note the term <i>class file</i> is used as defined in section 3.1 of
163 * <cite>The Java™ Virtual Machine Specification</cite>, to mean a
164 * sequence of bytes in class file format, whether or not they reside in a
165 * file.
166 *
167 * @see java.lang.instrument.Instrumentation
168 * @since 1.5
169 */
170
171 public interface ClassFileTransformer {
172 /**
173 * A {@code ClassDefiner} provides the mechanism for {@code ClassFileTransformer}
174 * to define additional classes during the
175 * {@linkplain ClassFileTransformer#transform(ClassDefiner, Module, ClassLoader, String, Class, ProtectionDomain, byte[])
176 * transformation process} of a class.
177 *
178 * <p> When a {@linkplain ClassFileTransformer#transform(ClassDefiner, Module, ClassLoader, String, Class, ProtectionDomain, byte[])
179 * transformer} is called to retransform a class, the transformer can call
180 * {@link ClassDefiner#defineClass(byte[])} to define additional classes.
181 * If it is called after {@link ClassFileTransformer#transform(ClassDefiner, Module, ClassLoader, String, Class, ProtectionDomain, byte[])
182 * ClassFileTransformer.tranform} method returns or called by another
183 * thread, {@code IllegalStateException} will be thrown.
184 *
185 * @since 11
186 */
187 static interface ClassDefiner {
188 /**
189 * Defines a class of the given bytes to the runtime.
190 * The given bytes will be defined to the same class loader and in the
191 * same runtime package and
192 * {@linkplain java.security.ProtectionDomain protection domain} as
193 * the class being transformed.
194 *
195 * <p> No transformation is applied to the bytes passed to this
196 * {@code ClassDefiner.defineClass} method.
197 * {@link Instrumentation#retransformClasses(Class[])} can be called
198 * later to retransform the {@code Class} returned by this method
199 * if desired.
200 *
201 * @param bytes the class bytes
202 * @return the {@code Class} object for the class
203 *
204 * @throws IllegalArgumentException
205 * the bytes are for a class of a different package than
206 * the class being transformed
207 * @throws LinkageError if the class is malformed ({@code ClassFormatError}),
208 * cannot be verified ({@code VerifyError}), is already defined,
209 * or another linkage error occurs
210 * @throws IllegalStateException if this {@code ClassDefiner} is called
211 * by a thread other than the thread doing the transformation,
212 * or after all transformers are called.
213 */
214 Class<?> defineClass(byte[] bytes);
215 }
216
217 /**
218 * Transforms the given class file and returns a new replacement class file.
219 * This method is invoked when the {@link Module Module} bearing {@link
220 * ClassFileTransformer#transform(Module,ClassLoader,String,Class,ProtectionDomain,byte[])
221 * transform} is not overridden.
222 *
223 * @implSpec The default implementation returns null.
224 *
225 * @param loader the defining loader of the class to be transformed,
226 * may be {@code null} if the bootstrap loader
227 * @param className the name of the class in the internal form of fully
228 * qualified class and interface names as defined in
229 * <i>The Java Virtual Machine Specification</i>.
230 * For example, <code>"java/util/List"</code>.
231 * @param classBeingRedefined if this is triggered by a redefine or retransform,
232 * the class being redefined or retransformed;
233 * if this is a class load, {@code null}
234 * @param protectionDomain the protection domain of the class being defined or redefined
235 * @param classfileBuffer the input byte buffer in class file format - must not be modified
236 *
237 * @throws IllegalClassFormatException
238 * if the input does not represent a well-formed class file
239 * @return a well-formed class file buffer (the result of the transform),
240 * or {@code null} if no transform is performed
241 *
242 * @revised 9
243 * @spec JPMS
244 */
245 default byte[]
246 transform( ClassLoader loader,
247 String className,
248 Class<?> classBeingRedefined,
249 ProtectionDomain protectionDomain,
250 byte[] classfileBuffer)
251 throws IllegalClassFormatException {
252 return null;
253 }
254
255
256 /**
257 * Transforms the given class file and returns a new replacement class file.
258 *
259 * @implSpec The default implementation of this method invokes the
260 * {@link #transform(ClassLoader,String,Class,ProtectionDomain,byte[]) transform}
261 * method.
262 *
263 * @param module the module of the class to be transformed
264 * @param loader the defining loader of the class to be transformed,
265 * may be {@code null} if the bootstrap loader
266 * @param className the name of the class in the internal form of fully
267 * qualified class and interface names as defined in
268 * <i>The Java Virtual Machine Specification</i>.
269 * For example, <code>"java/util/List"</code>.
270 * @param classBeingRedefined if this is triggered by a redefine or retransform,
271 * the class being redefined or retransformed;
272 * if this is a class load, {@code null}
273 * @param protectionDomain the protection domain of the class being defined or redefined
274 * @param classfileBuffer the input byte buffer in class file format - must not be modified
275 *
276 * @throws IllegalClassFormatException
277 * if the input does not represent a well-formed class file
278 * @return a well-formed class file buffer (the result of the transform),
279 * or {@code null} if no transform is performed
280 *
281 * @since 9
282 * @spec JPMS
283 */
284 default byte[]
285 transform( Module module,
286 ClassLoader loader,
287 String className,
288 Class<?> classBeingRedefined,
289 ProtectionDomain protectionDomain,
290 byte[] classfileBuffer)
291 throws IllegalClassFormatException {
292
293 // invoke the legacy transform method
294 return transform(loader,
295 className,
296 classBeingRedefined,
297 protectionDomain,
298 classfileBuffer);
299 }
300
301 /**
302 * Transforms the given class file and returns a new replacement class file.
303 *
304 * <p> A {@code ClassFileTransformer} may define additional classes
305 * to the same class loader and the same runtime package as the class being
306 * transformed by calling {@link ClassDefiner#defineClass(byte[])}
307 * classDefiner.defineClass} method. If an attempt to use {@code classDefiner}
308 * is made after this {@code transform} method returns,
309 * {@code IllegalStateException} will be thrown.
310 *
311 * @implSpec The default implementation of this method invokes the
312 * {@link #transform(Module,ClassLoader,String,Class,ProtectionDomain,byte[]) transform}
313 * method.
314 *
315 * @param classDefiner a {@code ClassDefiner} that this class transformer
316 * can define additional classes
317 * @param module the module of the class to be transformed
318 * @param loader the defining loader of the class to be transformed,
319 * may be {@code null} if the bootstrap loader
320 * @param className the name of the class in the internal form of fully
321 * qualified class and interface names as defined in
322 * <i>The Java Virtual Machine Specification</i>.
323 * For example, <code>"java/util/List"</code>.
324 * @param classBeingRedefined if this is triggered by a redefine or retransform,
325 * the class being redefined or retransformed;
326 * if this is a class load, {@code null}
327 * @param protectionDomain the protection domain of the class being defined or redefined
328 * @param classfileBuffer the input byte buffer in class file format - must not be modified
329 *
330 * @throws IllegalClassFormatException
331 * if the input does not represent a well-formed class file
332 * @return a well-formed class file buffer (the result of the transform),
333 * or {@code null} if no transform is performed
334 *
335 * @since 11
336 */
337 default byte[]
338 transform( ClassFileTransformer.ClassDefiner classDefiner,
339 Module module,
340 ClassLoader loader,
341 String className,
342 Class<?> classBeingRedefined,
343 ProtectionDomain protectionDomain,
344 byte[] classfileBuffer)
345 throws IllegalClassFormatException {
346
347 // invoke the transform method
348 return transform(module,
349 loader,
350 className,
351 classBeingRedefined,
352 protectionDomain,
353 classfileBuffer);
354 }
355 }