1 /*
2 * Copyright (c) 2003, 2011, 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.io.File;
29 import java.io.IOException;
30 import java.util.jar.JarFile;
31
32 /*
33 * Copyright 2003 Wily Technology, Inc.
34 */
35
36 /**
37 * This class provides services needed to instrument Java
38 * programming language code.
39 * Instrumentation is the addition of byte-codes to methods for the
40 * purpose of gathering data to be utilized by tools.
41 * Since the changes are purely additive, these tools do not modify
42 * application state or behavior.
43 * Examples of such benign tools include monitoring agents, profilers,
44 * coverage analyzers, and event loggers.
45 *
46 * <P>
47 * There are two ways to obtain an instance of the
48 * <code>Instrumentation</code> interface:
49 *
50 * <ol>
51 * <li><p> When a JVM is launched in a way that indicates an agent
52 * class. In that case an <code>Instrumentation</code> instance
53 * is passed to the <code>premain</code> method of the agent class.
54 * </p></li>
55 * <li><p> When a JVM provides a mechanism to start agents sometime
56 * after the JVM is launched. In that case an <code>Instrumentation</code>
57 * instance is passed to the <code>agentmain</code> method of the
58 * agent code. </p> </li>
59 * </ol>
60 * <p>
61 * These mechanisms are described in the
62 * {@linkplain java.lang.instrument package specification}.
63 * <p>
64 * Once an agent acquires an <code>Instrumentation</code> instance,
65 * the agent may call methods on the instance at any time.
66 *
67 * @since 1.5
68 */
69 public interface Instrumentation {
70 /**
71 * Registers the supplied transformer. All future class definitions
72 * will be seen by the transformer, except definitions of classes upon which any
73 * registered transformer is dependent.
74 * The transformer is called when classes are loaded, when they are
75 * {@linkplain #redefineClasses redefined}. and if <code>canRetransform</code> is true,
76 * when they are {@linkplain #retransformClasses retransformed}.
77 * See {@link java.lang.instrument.ClassFileTransformer#transform
78 * ClassFileTransformer.transform} for the order
79 * of transform calls.
80 * If a transformer throws
81 * an exception during execution, the JVM will still call the other registered
82 * transformers in order. The same transformer may be added more than once,
83 * but it is strongly discouraged -- avoid this by creating a new instance of
84 * transformer class.
85 * <P>
86 * This method is intended for use in instrumentation, as described in the
87 * {@linkplain Instrumentation class specification}.
88 *
89 * @param transformer the transformer to register
90 * @param canRetransform can this transformer's transformations be retransformed
91 * @throws java.lang.NullPointerException if passed a <code>null</code> transformer
92 * @throws java.lang.UnsupportedOperationException if <code>canRetransform</code>
93 * is true and the current configuration of the JVM does not allow
94 * retransformation ({@link #isRetransformClassesSupported} is false)
95 * @since 1.6
96 */
97 void
98 addTransformer(ClassFileTransformer transformer, boolean canRetransform);
99
100 /**
101 * Registers the supplied transformer.
102 * <P>
103 * Same as <code>addTransformer(transformer, false)</code>.
104 *
105 * @param transformer the transformer to register
106 * @throws java.lang.NullPointerException if passed a <code>null</code> transformer
107 * @see #addTransformer(ClassFileTransformer,boolean)
108 */
109 void
110 addTransformer(ClassFileTransformer transformer);
111
112 /**
113 * Unregisters the supplied transformer. Future class definitions will
114 * not be shown to the transformer. Removes the most-recently-added matching
115 * instance of the transformer. Due to the multi-threaded nature of
116 * class loading, it is possible for a transformer to receive calls
117 * after it has been removed. Transformers should be written defensively
118 * to expect this situation.
119 *
120 * @param transformer the transformer to unregister
121 * @return true if the transformer was found and removed, false if the
122 * transformer was not found
123 * @throws java.lang.NullPointerException if passed a <code>null</code> transformer
124 */
125 boolean
126 removeTransformer(ClassFileTransformer transformer);
127
128 /**
129 * Returns whether or not the current JVM configuration supports retransformation
130 * of classes.
131 * The ability to retransform an already loaded class is an optional capability
132 * of a JVM.
133 * Retransformation will only be supported if the
134 * <code>Can-Retransform-Classes</code> manifest attribute is set to
135 * <code>true</code> in the agent JAR file (as described in the
136 * {@linkplain java.lang.instrument package specification}) and the JVM supports
137 * this capability.
138 * During a single instantiation of a single JVM, multiple calls to this
139 * method will always return the same answer.
140 * @return true if the current JVM configuration supports retransformation of
141 * classes, false if not.
142 * @see #retransformClasses
143 * @since 1.6
144 */
145 boolean
146 isRetransformClassesSupported();
147
148 /**
149 * Retransform the supplied set of classes.
150 *
151 * <P>
152 * This function facilitates the instrumentation
153 * of already loaded classes.
154 * When classes are initially loaded or when they are
155 * {@linkplain #redefineClasses redefined},
156 * the initial class file bytes can be transformed with the
157 * {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer}.
158 * This function reruns the transformation process
159 * (whether or not a transformation has previously occurred).
160 * This retransformation follows these steps:
161 * <ul>
162 * <li>starting from the initial class file bytes
163 * </li>
164 * <li>for each transformer that was added with <code>canRetransform</code>
165 * false, the bytes returned by
166 * {@link java.lang.instrument.ClassFileTransformer#transform transform}
167 * during the last class load or redefine are
168 * reused as the output of the transformation; note that this is
169 * equivalent to reapplying the previous transformation, unaltered;
170 * except that
171 * {@link java.lang.instrument.ClassFileTransformer#transform transform}
172 * is not called
173 * </li>
174 * <li>for each transformer that was added with <code>canRetransform</code>
175 * true, the
176 * {@link java.lang.instrument.ClassFileTransformer#transform transform}
177 * method is called in these transformers
178 * </li>
179 * <li>the transformed class file bytes are installed as the new
180 * definition of the class
181 * </li>
182 * </ul>
183 * <P>
184 *
185 * The order of transformation is described in the
186 * {@link java.lang.instrument.ClassFileTransformer#transform transform} method.
187 * This same order is used in the automatic reapplication of retransformation
188 * incapable transforms.
189 * <P>
190 *
191 * The initial class file bytes represent the bytes passed to
192 * {@link java.lang.ClassLoader#defineClass ClassLoader.defineClass} or
193 * {@link #redefineClasses redefineClasses}
194 * (before any transformations
195 * were applied), however they might not exactly match them.
196 * The constant pool might not have the same layout or contents.
197 * The constant pool may have more or fewer entries.
198 * Constant pool entries may be in a different order; however,
199 * constant pool indices in the bytecodes of methods will correspond.
200 * Some attributes may not be present.
201 * Where order is not meaningful, for example the order of methods,
202 * order might not be preserved.
203 *
204 * <P>
205 * This method operates on
206 * a set in order to allow interdependent changes to more than one class at the same time
207 * (a retransformation of class A can require a retransformation of class B).
208 *
209 * <P>
210 * If a retransformed method has active stack frames, those active frames continue to
211 * run the bytecodes of the original method.
212 * The retransformed method will be used on new invokes.
213 *
214 * <P>
215 * This method does not cause any initialization except that which would occur
216 * under the customary JVM semantics. In other words, redefining a class
217 * does not cause its initializers to be run. The values of static variables
218 * will remain as they were prior to the call.
219 *
220 * <P>
221 * Instances of the retransformed class are not affected.
222 *
223 * <P>
224 * The retransformation may change method bodies, the constant pool and attributes.
225 * The retransformation must not add, remove or rename fields or methods, change the
226 * signatures of methods, or change inheritance. These restrictions maybe be
227 * lifted in future versions. The class file bytes are not checked, verified and installed
228 * until after the transformations have been applied, if the resultant bytes are in
229 * error this method will throw an exception.
230 *
231 * <P>
232 * If this method throws an exception, no classes have been retransformed.
233 * <P>
234 * This method is intended for use in instrumentation, as described in the
235 * {@linkplain Instrumentation class specification}.
236 *
237 * @param classes array of classes to retransform;
238 * a zero-length array is allowed, in this case, this method does nothing
239 * @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified
240 * ({@link #isModifiableClass} would return <code>false</code>)
241 * @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow
242 * retransformation ({@link #isRetransformClassesSupported} is false) or the retransformation attempted
243 * to make unsupported changes
244 * @throws java.lang.ClassFormatError if the data did not contain a valid class
245 * @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class
246 * @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported
247 * @throws java.lang.ClassCircularityError if the new classes contain a circularity
248 * @throws java.lang.LinkageError if a linkage error occurs
249 * @throws java.lang.NullPointerException if the supplied classes array or any of its components
250 * is <code>null</code>.
251 *
252 * @see #isRetransformClassesSupported
253 * @see #addTransformer
254 * @see java.lang.instrument.ClassFileTransformer
255 * @since 1.6
256 */
257 void
258 retransformClasses(Class<?>... classes) throws UnmodifiableClassException;
259
260 /**
261 * Returns whether or not the current JVM configuration supports redefinition
262 * of classes.
263 * The ability to redefine an already loaded class is an optional capability
264 * of a JVM.
265 * Redefinition will only be supported if the
266 * <code>Can-Redefine-Classes</code> manifest attribute is set to
267 * <code>true</code> in the agent JAR file (as described in the
268 * {@linkplain java.lang.instrument package specification}) and the JVM supports
269 * this capability.
270 * During a single instantiation of a single JVM, multiple calls to this
271 * method will always return the same answer.
272 * @return true if the current JVM configuration supports redefinition of classes,
273 * false if not.
274 * @see #redefineClasses
275 */
276 boolean
277 isRedefineClassesSupported();
278
279 /**
280 * Redefine the supplied set of classes using the supplied class files.
281 *
282 * <P>
283 * This method is used to replace the definition of a class without reference
284 * to the existing class file bytes, as one might do when recompiling from source
285 * for fix-and-continue debugging.
286 * Where the existing class file bytes are to be transformed (for
287 * example in bytecode instrumentation)
288 * {@link #retransformClasses retransformClasses}
289 * should be used.
290 *
291 * <P>
292 * This method operates on
293 * a set in order to allow interdependent changes to more than one class at the same time
294 * (a redefinition of class A can require a redefinition of class B).
295 *
296 * <P>
297 * If a redefined method has active stack frames, those active frames continue to
298 * run the bytecodes of the original method.
299 * The redefined method will be used on new invokes.
300 *
301 * <P>
302 * This method does not cause any initialization except that which would occur
303 * under the customary JVM semantics. In other words, redefining a class
304 * does not cause its initializers to be run. The values of static variables
305 * will remain as they were prior to the call.
306 *
307 * <P>
308 * Instances of the redefined class are not affected.
309 *
310 * <P>
311 * The redefinition may change method bodies, the constant pool and attributes.
312 * The redefinition must not add, remove or rename fields or methods, change the
313 * signatures of methods, or change inheritance. These restrictions maybe be
314 * lifted in future versions. The class file bytes are not checked, verified and installed
315 * until after the transformations have been applied, if the resultant bytes are in
316 * error this method will throw an exception.
317 *
318 * <P>
319 * If this method throws an exception, no classes have been redefined.
320 * <P>
321 * This method is intended for use in instrumentation, as described in the
322 * {@linkplain Instrumentation class specification}.
323 *
324 * @param definitions array of classes to redefine with corresponding definitions;
325 * a zero-length array is allowed, in this case, this method does nothing
326 * @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified
327 * ({@link #isModifiableClass} would return <code>false</code>)
328 * @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow
329 * redefinition ({@link #isRedefineClassesSupported} is false) or the redefinition attempted
330 * to make unsupported changes
331 * @throws java.lang.ClassFormatError if the data did not contain a valid class
332 * @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class
333 * @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported
334 * @throws java.lang.ClassCircularityError if the new classes contain a circularity
335 * @throws java.lang.LinkageError if a linkage error occurs
336 * @throws java.lang.NullPointerException if the supplied definitions array or any of its components
337 * is <code>null</code>
338 * @throws java.lang.ClassNotFoundException Can never be thrown (present for compatibility reasons only)
339 *
340 * @see #isRedefineClassesSupported
341 * @see #addTransformer
342 * @see java.lang.instrument.ClassFileTransformer
343 */
344 void
345 redefineClasses(ClassDefinition... definitions)
346 throws ClassNotFoundException, UnmodifiableClassException;
347
348
349 /**
350 * Determines whether a class is modifiable by
351 * {@linkplain #retransformClasses retransformation}
352 * or {@linkplain #redefineClasses redefinition}.
353 * If a class is modifiable then this method returns <code>true</code>.
354 * If a class is not modifiable then this method returns <code>false</code>.
355 * <P>
356 * For a class to be retransformed, {@link #isRetransformClassesSupported} must also be true.
357 * But the value of <code>isRetransformClassesSupported()</code> does not influence the value
358 * returned by this function.
359 * For a class to be redefined, {@link #isRedefineClassesSupported} must also be true.
360 * But the value of <code>isRedefineClassesSupported()</code> does not influence the value
361 * returned by this function.
362 * <P>
363 * Primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
364 * and array classes are never modifiable.
365 *
366 * @throws java.lang.NullPointerException if the specified class is <code>null</code>.
367 *
368 * @see #retransformClasses
369 * @see #isRetransformClassesSupported
370 * @see #redefineClasses
371 * @see #isRedefineClassesSupported
372 * @since 1.6
373 */
374 boolean
375 isModifiableClass(Class<?> theClass);
376
377 /**
378 * Returns an array of all classes currently loaded by the JVM.
379 *
380 * @return an array containing all the classes loaded by the JVM, zero-length if there are none
381 */
382 Class[]
383 getAllLoadedClasses();
384
385 /**
386 * Returns an array of all classes for which <code>loader</code> is an initiating loader.
387 * If the supplied loader is <code>null</code>, classes initiated by the bootstrap class
388 * loader are returned.
389 *
390 * @param loader the loader whose initiated class list will be returned
391 * @return an array containing all the classes for which loader is an initiating loader,
392 * zero-length if there are none
393 */
394 Class[]
395 getInitiatedClasses(ClassLoader loader);
396
397 /**
398 * Returns an implementation-specific approximation of the amount of storage consumed by
399 * the specified object. The result may include some or all of the object's overhead,
400 * and thus is useful for comparison within an implementation but not between implementations.
401 *
402 * The estimate may change during a single invocation of the JVM.
403 *
404 * @param objectToSize the object to size
405 * @return an implementation-specific approximation of the amount of storage consumed by the specified object
406 * @throws java.lang.NullPointerException if the supplied Object is <code>null</code>.
407 */
408 long
409 getObjectSize(Object objectToSize);
410
411
412 /**
413 * Specifies a JAR file with instrumentation classes to be defined by the
414 * bootstrap class loader.
415 *
416 * <p> When the virtual machine's built-in class loader, known as the "bootstrap
417 * class loader", unsuccessfully searches for a class, the entries in the {@link
418 * java.util.jar.JarFile JAR file} will be searched as well.
419 *
420 * <p> This method may be used multiple times to add multiple JAR files to be
421 * searched in the order that this method was invoked.
422 *
423 * <p> The agent should take care to ensure that the JAR does not contain any
424 * classes or resources other than those to be defined by the bootstrap
425 * class loader for the purpose of instrumentation.
426 * Failure to observe this warning could result in unexpected
427 * behavior that is difficult to diagnose. For example, suppose there is a
428 * loader L, and L's parent for delegation is the bootstrap class loader.
429 * Furthermore, a method in class C, a class defined by L, makes reference to
430 * a non-public accessor class C$1. If the JAR file contains a class C$1 then
431 * the delegation to the bootstrap class loader will cause C$1 to be defined
432 * by the bootstrap class loader. In this example an <code>IllegalAccessError</code>
433 * will be thrown that may cause the application to fail. One approach to
434 * avoiding these types of issues, is to use a unique package name for the
435 * instrumentation classes.
436 *
437 * <p>
438 * <cite>The Java™ Virtual Machine Specification</cite>
439 * specifies that a subsequent attempt to resolve a symbolic
440 * reference that the Java virtual machine has previously unsuccessfully attempted
441 * to resolve always fails with the same error that was thrown as a result of the
442 * initial resolution attempt. Consequently, if the JAR file contains an entry
443 * that corresponds to a class for which the Java virtual machine has
444 * unsuccessfully attempted to resolve a reference, then subsequent attempts to
445 * resolve that reference will fail with the same error as the initial attempt.
446 *
447 * @param jarfile
448 * The JAR file to be searched when the bootstrap class loader
449 * unsuccessfully searches for a class.
450 *
451 * @throws NullPointerException
452 * If <code>jarfile</code> is <code>null</code>.
453 *
454 * @see #appendToSystemClassLoaderSearch
455 * @see java.lang.ClassLoader
456 * @see java.util.jar.JarFile
457 *
458 * @since 1.6
459 */
460 void
461 appendToBootstrapClassLoaderSearch(JarFile jarfile);
462
463 /**
464 * Specifies a JAR file with instrumentation classes to be defined by the
465 * system class loader.
466 *
467 * When the system class loader for delegation (see
468 * {@link java.lang.ClassLoader#getSystemClassLoader getSystemClassLoader()})
469 * unsuccessfully searches for a class, the entries in the {@link
470 * java.util.jar.JarFile JarFile} will be searched as well.
471 *
472 * <p> This method may be used multiple times to add multiple JAR files to be
473 * searched in the order that this method was invoked.
474 *
475 * <p> The agent should take care to ensure that the JAR does not contain any
476 * classes or resources other than those to be defined by the system class
477 * loader for the purpose of instrumentation.
478 * Failure to observe this warning could result in unexpected
479 * behavior that is difficult to diagnose (see
480 * {@link #appendToBootstrapClassLoaderSearch
481 * appendToBootstrapClassLoaderSearch}).
482 *
483 * <p> The system class loader supports adding a JAR file to be searched if
484 * it implements a method named <code>appendToClassPathForInstrumentation</code>
485 * which takes a single parameter of type <code>java.lang.String</code>. The
486 * method is not required to have <code>public</code> access. The name of
487 * the JAR file is obtained by invoking the {@link java.util.zip.ZipFile#getName
488 * getName()} method on the <code>jarfile</code> and this is provided as the
489 * parameter to the <code>appendToClassPathForInstrumentation</code> method.
490 *
491 * <p>
492 * <cite>The Java™ Virtual Machine Specification</cite>
493 * specifies that a subsequent attempt to resolve a symbolic
494 * reference that the Java virtual machine has previously unsuccessfully attempted
495 * to resolve always fails with the same error that was thrown as a result of the
496 * initial resolution attempt. Consequently, if the JAR file contains an entry
497 * that corresponds to a class for which the Java virtual machine has
498 * unsuccessfully attempted to resolve a reference, then subsequent attempts to
499 * resolve that reference will fail with the same error as the initial attempt.
500 *
501 * <p> This method does not change the value of <code>java.class.path</code>
502 * {@link java.lang.System#getProperties system property}.
503 *
504 * @param jarfile
505 * The JAR file to be searched when the system class loader
506 * unsuccessfully searches for a class.
507 *
508 * @throws UnsupportedOperationException
509 * If the system class loader does not support appending a
510 * a JAR file to be searched.
511 *
512 * @throws NullPointerException
513 * If <code>jarfile</code> is <code>null</code>.
514 *
515 * @see #appendToBootstrapClassLoaderSearch
516 * @see java.lang.ClassLoader#getSystemClassLoader
517 * @see java.util.jar.JarFile
518 * @since 1.6
519 */
520 void
521 appendToSystemClassLoaderSearch(JarFile jarfile);
522
523 /**
524 * Returns whether the current JVM configuration supports
525 * {@linkplain #setNativeMethodPrefix(ClassFileTransformer,String)
526 * setting a native method prefix}.
527 * The ability to set a native method prefix is an optional
528 * capability of a JVM.
529 * Setting a native method prefix will only be supported if the
530 * <code>Can-Set-Native-Method-Prefix</code> manifest attribute is set to
531 * <code>true</code> in the agent JAR file (as described in the
532 * {@linkplain java.lang.instrument package specification}) and the JVM supports
533 * this capability.
534 * During a single instantiation of a single JVM, multiple
535 * calls to this method will always return the same answer.
536 * @return true if the current JVM configuration supports
537 * setting a native method prefix, false if not.
538 * @see #setNativeMethodPrefix
539 * @since 1.6
540 */
541 boolean
542 isNativeMethodPrefixSupported();
543
544 /**
545 * This method modifies the failure handling of
546 * native method resolution by allowing retry
547 * with a prefix applied to the name.
548 * When used with the
549 * {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer},
550 * it enables native methods to be
551 * instrumented.
552 * <p/>
553 * Since native methods cannot be directly instrumented
554 * (they have no bytecodes), they must be wrapped with
555 * a non-native method which can be instrumented.
556 * For example, if we had:
557 * <pre>
558 * native boolean foo(int x);</pre>
559 * <p/>
560 * We could transform the class file (with the
561 * ClassFileTransformer during the initial definition
562 * of the class) so that this becomes:
563 * <pre>
564 * boolean foo(int x) {
565 * <i>... record entry to foo ...</i>
566 * return wrapped_foo(x);
567 * }
568 *
569 * native boolean wrapped_foo(int x);</pre>
570 * <p/>
571 * Where <code>foo</code> becomes a wrapper for the actual native
572 * method with the appended prefix "wrapped_". Note that
573 * "wrapped_" would be a poor choice of prefix since it
574 * might conceivably form the name of an existing method
575 * thus something like "$$$MyAgentWrapped$$$_" would be
576 * better but would make these examples less readable.
577 * <p/>
578 * The wrapper will allow data to be collected on the native
579 * method call, but now the problem becomes linking up the
580 * wrapped method with the native implementation.
581 * That is, the method <code>wrapped_foo</code> needs to be
582 * resolved to the native implementation of <code>foo</code>,
583 * which might be:
584 * <pre>
585 * Java_somePackage_someClass_foo(JNIEnv* env, jint x)</pre>
586 * <p/>
587 * This function allows the prefix to be specified and the
588 * proper resolution to occur.
589 * Specifically, when the standard resolution fails, the
590 * resolution is retried taking the prefix into consideration.
591 * There are two ways that resolution occurs, explicit
592 * resolution with the JNI function <code>RegisterNatives</code>
593 * and the normal automatic resolution. For
594 * <code>RegisterNatives</code>, the JVM will attempt this
595 * association:
596 * <pre>{@code
597 * method(foo) -> nativeImplementation(foo)
598 * }</pre>
599 * <p/>
600 * When this fails, the resolution will be retried with
601 * the specified prefix prepended to the method name,
602 * yielding the correct resolution:
603 * <pre>{@code
604 * method(wrapped_foo) -> nativeImplementation(foo)
605 * }</pre>
606 * <p/>
607 * For automatic resolution, the JVM will attempt:
608 * <pre>{@code
609 * method(wrapped_foo) -> nativeImplementation(wrapped_foo)
610 * }</pre>
611 * <p/>
612 * When this fails, the resolution will be retried with
613 * the specified prefix deleted from the implementation name,
614 * yielding the correct resolution:
615 * <pre>{@code
616 * method(wrapped_foo) -> nativeImplementation(foo)
617 * }</pre>
618 * <p/>
619 * Note that since the prefix is only used when standard
620 * resolution fails, native methods can be wrapped selectively.
621 * <p/>
622 * Since each <code>ClassFileTransformer</code>
623 * can do its own transformation of the bytecodes, more
624 * than one layer of wrappers may be applied. Thus each
625 * transformer needs its own prefix. Since transformations
626 * are applied in order, the prefixes, if applied, will
627 * be applied in the same order
628 * (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}).
629 * Thus if three transformers applied
630 * wrappers, <code>foo</code> might become
631 * <code>$trans3_$trans2_$trans1_foo</code>. But if, say,
632 * the second transformer did not apply a wrapper to
633 * <code>foo</code> it would be just
634 * <code>$trans3_$trans1_foo</code>. To be able to
635 * efficiently determine the sequence of prefixes,
636 * an intermediate prefix is only applied if its non-native
637 * wrapper exists. Thus, in the last example, even though
638 * <code>$trans1_foo</code> is not a native method, the
639 * <code>$trans1_</code> prefix is applied since
640 * <code>$trans1_foo</code> exists.
641 *
642 * @param transformer
643 * The ClassFileTransformer which wraps using this prefix.
644 * @param prefix
645 * The prefix to apply to wrapped native methods when
646 * retrying a failed native method resolution. If prefix
647 * is either <code>null</code> or the empty string, then
648 * failed native method resolutions are not retried for
649 * this transformer.
650 * @throws java.lang.NullPointerException if passed a <code>null</code> transformer.
651 * @throws java.lang.UnsupportedOperationException if the current configuration of
652 * the JVM does not allow setting a native method prefix
653 * ({@link #isNativeMethodPrefixSupported} is false).
654 * @throws java.lang.IllegalArgumentException if the transformer is not registered
655 * (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}).
656 *
657 * @since 1.6
658 */
659 void
660 setNativeMethodPrefix(ClassFileTransformer transformer, String prefix);
661 }