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