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