1 /*
2 * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.instrument;
27
28 import java.security.ProtectionDomain;
29 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 attributes.
223 * The retransformation must not add, remove or rename fields or methods, change the
224 * signatures of methods, or change inheritance. These restrictions maybe be
225 * lifted in future versions. The class file bytes are not checked, verified and installed
226 * until after the transformations have been applied, if the resultant bytes are in
227 * error this method will throw an exception.
228 *
229 * <P>
230 * If this method throws an exception, no classes have been retransformed.
231 * <P>
232 * This method is intended for use in instrumentation, as described in the
233 * {@linkplain Instrumentation class specification}.
234 *
235 * @param classes array of classes to retransform;
236 * a zero-length array is allowed, in this case, this method does nothing
237 * @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified
238 * ({@link #isModifiableClass} would return <code>false</code>)
239 * @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow
240 * retransformation ({@link #isRetransformClassesSupported} is false) or the retransformation attempted
241 * to make unsupported changes
242 * @throws java.lang.ClassFormatError if the data did not contain a valid class
243 * @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class
244 * @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported
245 * @throws java.lang.ClassCircularityError if the new classes contain a circularity
246 * @throws java.lang.LinkageError if a linkage error occurs
247 * @throws java.lang.NullPointerException if the supplied classes array or any of its components
248 * is <code>null</code>.
249 *
250 * @see #isRetransformClassesSupported
251 * @see #addTransformer
252 * @see java.lang.instrument.ClassFileTransformer
253 * @since 1.6
254 */
255 void
256 retransformClasses(Class<?>... classes) throws UnmodifiableClassException;
257
258 /**
259 * Returns whether or not the current JVM configuration supports redefinition
260 * of classes.
261 * The ability to redefine an already loaded class is an optional capability
262 * of a JVM.
263 * Redefinition will only be supported if the
264 * <code>Can-Redefine-Classes</code> manifest attribute is set to
265 * <code>true</code> in the agent JAR file (as described in the
266 * {@linkplain java.lang.instrument package specification}) and the JVM supports
267 * this capability.
268 * During a single instantiation of a single JVM, multiple calls to this
269 * method will always return the same answer.
270 * @return true if the current JVM configuration supports redefinition of classes,
271 * false if not.
272 * @see #redefineClasses
273 */
274 boolean
275 isRedefineClassesSupported();
276
277 /**
278 * Redefine the supplied set of classes using the supplied class files.
279 *
280 * <P>
281 * This method is used to replace the definition of a class without reference
282 * to the existing class file bytes, as one might do when recompiling from source
283 * for fix-and-continue debugging.
284 * Where the existing class file bytes are to be transformed (for
285 * example in bytecode instrumentation)
286 * {@link #retransformClasses retransformClasses}
287 * should be used.
288 *
289 * <P>
290 * This method operates on
291 * a set in order to allow interdependent changes to more than one class at the same time
292 * (a redefinition of class A can require a redefinition of class B).
293 *
294 * <P>
295 * If a redefined method has active stack frames, those active frames continue to
296 * run the bytecodes of the original method.
297 * The redefined method will be used on new invokes.
298 *
299 * <P>
300 * This method does not cause any initialization except that which would occur
301 * under the customary JVM semantics. In other words, redefining a class
302 * does not cause its initializers to be run. The values of static variables
303 * will remain as they were prior to the call.
304 *
305 * <P>
306 * Instances of the redefined class are not affected.
307 *
308 * <P>
309 * The redefinition may change method bodies, the constant pool and attributes.
310 * The redefinition must not add, remove or rename fields or methods, change the
311 * signatures of methods, or change inheritance. These restrictions maybe be
312 * lifted in future versions. The class file bytes are not checked, verified and installed
313 * until after the transformations have been applied, if the resultant bytes are in
314 * error this method will throw an exception.
315 *
316 * <P>
317 * If this method throws an exception, no classes have been redefined.
318 * <P>
319 * This method is intended for use in instrumentation, as described in the
320 * {@linkplain Instrumentation class specification}.
321 *
322 * @param definitions array of classes to redefine with corresponding definitions;
323 * a zero-length array is allowed, in this case, this method does nothing
324 * @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified
325 * ({@link #isModifiableClass} would return <code>false</code>)
326 * @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow
327 * redefinition ({@link #isRedefineClassesSupported} is false) or the redefinition attempted
328 * to make unsupported changes
329 * @throws java.lang.ClassFormatError if the data did not contain a valid class
330 * @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class
331 * @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported
332 * @throws java.lang.ClassCircularityError if the new classes contain a circularity
333 * @throws java.lang.LinkageError if a linkage error occurs
334 * @throws java.lang.NullPointerException if the supplied definitions array or any of its components
335 * is <code>null</code>
336 * @throws java.lang.ClassNotFoundException Can never be thrown (present for compatibility reasons only)
337 *
338 * @see #isRedefineClassesSupported
339 * @see #addTransformer
340 * @see java.lang.instrument.ClassFileTransformer
341 */
342 void
343 redefineClasses(ClassDefinition... definitions)
344 throws ClassNotFoundException, UnmodifiableClassException;
345
346
347 /**
348 * Tests whether a class is modifiable by
349 * {@linkplain #retransformClasses retransformation}
350 * or {@linkplain #redefineClasses redefinition}.
351 * If a class is modifiable then this method returns <code>true</code>.
352 * If a class is not modifiable then this method returns <code>false</code>.
353 * <P>
354 * For a class to be retransformed, {@link #isRetransformClassesSupported} must also be true.
355 * But the value of <code>isRetransformClassesSupported()</code> does not influence the value
356 * returned by this function.
357 * For a class to be redefined, {@link #isRedefineClassesSupported} must also be true.
358 * But the value of <code>isRedefineClassesSupported()</code> does not influence the value
359 * returned by this function.
360 * <P>
361 * Primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
362 * and array classes are never modifiable.
363 *
364 * @param theClass the class to check for being modifiable
365 * @return whether or not the argument class is modifiable
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 @SuppressWarnings("rawtypes")
383 Class[]
384 getAllLoadedClasses();
385
386 /**
387 * Returns an array of all classes for which <code>loader</code> is an initiating loader.
388 * If the supplied loader is <code>null</code>, classes initiated by the bootstrap class
389 * loader are returned.
390 *
391 * @param loader the loader whose initiated class list will be returned
392 * @return an array containing all the classes for which loader is an initiating loader,
393 * zero-length if there are none
394 */
395 @SuppressWarnings("rawtypes")
396 Class[]
397 getInitiatedClasses(ClassLoader loader);
398
399 /**
400 * Returns an implementation-specific approximation of the amount of storage consumed by
401 * the specified object. The result may include some or all of the object's overhead,
402 * and thus is useful for comparison within an implementation but not between implementations.
403 *
404 * The estimate may change during a single invocation of the JVM.
405 *
406 * @param objectToSize the object to size
407 * @return an implementation-specific approximation of the amount of storage consumed by the specified object
408 * @throws java.lang.NullPointerException if the supplied Object is <code>null</code>.
409 */
410 long
411 getObjectSize(Object objectToSize);
412
413
414 /**
415 * Specifies a JAR file with instrumentation classes to be defined by the
416 * bootstrap class loader.
417 *
418 * <p> When the virtual machine's built-in class loader, known as the "bootstrap
419 * class loader", unsuccessfully searches for a class, the entries in the {@link
420 * java.util.jar.JarFile JAR file} will be searched as well.
421 *
422 * <p> This method may be used multiple times to add multiple JAR files to be
423 * searched in the order that this method was invoked.
424 *
425 * <p> The agent should take care to ensure that the JAR does not contain any
426 * classes or resources other than those to be defined by the bootstrap
427 * class loader for the purpose of instrumentation.
428 * Failure to observe this warning could result in unexpected
429 * behavior that is difficult to diagnose. For example, suppose there is a
430 * loader L, and L's parent for delegation is the bootstrap class loader.
431 * Furthermore, a method in class C, a class defined by L, makes reference to
432 * a non-public accessor class C$1. If the JAR file contains a class C$1 then
433 * the delegation to the bootstrap class loader will cause C$1 to be defined
434 * by the bootstrap class loader. In this example an <code>IllegalAccessError</code>
435 * will be thrown that may cause the application to fail. One approach to
436 * avoiding these types of issues, is to use a unique package name for the
437 * instrumentation classes.
438 *
439 * <p>
440 * <cite>The Java™ Virtual Machine Specification</cite>
441 * specifies that a subsequent attempt to resolve a symbolic
442 * reference that the Java virtual machine has previously unsuccessfully attempted
443 * to resolve always fails with the same error that was thrown as a result of the
444 * initial resolution attempt. Consequently, if the JAR file contains an entry
445 * that corresponds to a class for which the Java virtual machine has
446 * unsuccessfully attempted to resolve a reference, then subsequent attempts to
447 * resolve that reference will fail with the same error as the initial attempt.
448 *
449 * @param jarfile
450 * The JAR file to be searched when the bootstrap class loader
451 * unsuccessfully searches for a class.
452 *
453 * @throws NullPointerException
454 * If <code>jarfile</code> is <code>null</code>.
455 *
456 * @see #appendToSystemClassLoaderSearch
457 * @see java.lang.ClassLoader
458 * @see java.util.jar.JarFile
459 *
460 * @since 1.6
461 */
462 void
463 appendToBootstrapClassLoaderSearch(JarFile jarfile);
464
465 /**
466 * Specifies a JAR file with instrumentation classes to be defined by the
467 * system class loader.
468 *
469 * When the system class loader for delegation (see
470 * {@link java.lang.ClassLoader#getSystemClassLoader getSystemClassLoader()})
471 * unsuccessfully searches for a class, the entries in the {@link
472 * java.util.jar.JarFile JarFile} will be searched as well.
473 *
474 * <p> This method may be used multiple times to add multiple JAR files to be
475 * searched in the order that this method was invoked.
476 *
477 * <p> The agent should take care to ensure that the JAR does not contain any
478 * classes or resources other than those to be defined by the system class
479 * loader for the purpose of instrumentation.
480 * Failure to observe this warning could result in unexpected
481 * behavior that is difficult to diagnose (see
482 * {@link #appendToBootstrapClassLoaderSearch
483 * appendToBootstrapClassLoaderSearch}).
484 *
485 * <p> The system class loader supports adding a JAR file to be searched if
486 * it implements a method named <code>appendToClassPathForInstrumentation</code>
487 * which takes a single parameter of type <code>java.lang.String</code>. The
488 * method is not required to have <code>public</code> access. The name of
489 * the JAR file is obtained by invoking the {@link java.util.zip.ZipFile#getName
490 * getName()} method on the <code>jarfile</code> and this is provided as the
491 * parameter to the <code>appendToClassPathForInstrumentation</code> method.
492 *
493 * <p>
494 * <cite>The Java™ Virtual Machine Specification</cite>
495 * specifies that a subsequent attempt to resolve a symbolic
496 * reference that the Java virtual machine has previously unsuccessfully attempted
497 * to resolve always fails with the same error that was thrown as a result of the
498 * initial resolution attempt. Consequently, if the JAR file contains an entry
499 * that corresponds to a class for which the Java virtual machine has
500 * unsuccessfully attempted to resolve a reference, then subsequent attempts to
501 * resolve that reference will fail with the same error as the initial attempt.
502 *
503 * <p> This method does not change the value of <code>java.class.path</code>
504 * {@link java.lang.System#getProperties system property}.
505 *
506 * @param jarfile
507 * The JAR file to be searched when the system class loader
508 * unsuccessfully searches for a class.
509 *
510 * @throws UnsupportedOperationException
511 * If the system class loader does not support appending a
512 * a JAR file to be searched.
513 *
514 * @throws NullPointerException
515 * If <code>jarfile</code> is <code>null</code>.
516 *
517 * @see #appendToBootstrapClassLoaderSearch
518 * @see java.lang.ClassLoader#getSystemClassLoader
519 * @see java.util.jar.JarFile
520 * @since 1.6
521 */
522 void
523 appendToSystemClassLoaderSearch(JarFile jarfile);
524
525 /**
526 * Returns whether the current JVM configuration supports
527 * {@linkplain #setNativeMethodPrefix(ClassFileTransformer,String)
528 * setting a native method prefix}.
529 * The ability to set a native method prefix is an optional
530 * capability of a JVM.
531 * Setting a native method prefix will only be supported if the
532 * <code>Can-Set-Native-Method-Prefix</code> manifest attribute is set to
533 * <code>true</code> in the agent JAR file (as described in the
534 * {@linkplain java.lang.instrument package specification}) and the JVM supports
535 * this capability.
536 * During a single instantiation of a single JVM, multiple
537 * calls to this method will always return the same answer.
538 * @return true if the current JVM configuration supports
539 * setting a native method prefix, false if not.
540 * @see #setNativeMethodPrefix
541 * @since 1.6
542 */
543 boolean
544 isNativeMethodPrefixSupported();
545
546 /**
547 * This method modifies the failure handling of
548 * native method resolution by allowing retry
549 * with a prefix applied to the name.
550 * When used with the
551 * {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer},
552 * it enables native methods to be
553 * instrumented.
554 * <p>
555 * Since native methods cannot be directly instrumented
556 * (they have no bytecodes), they must be wrapped with
557 * a non-native method which can be instrumented.
558 * For example, if we had:
559 * <pre>
560 * native boolean foo(int x);</pre>
561 * <p>
562 * We could transform the class file (with the
563 * ClassFileTransformer during the initial definition
564 * of the class) so that this becomes:
565 * <pre>
566 * boolean foo(int x) {
567 * <i>... record entry to foo ...</i>
568 * return wrapped_foo(x);
569 * }
570 *
571 * native boolean wrapped_foo(int x);</pre>
572 * <p>
573 * Where <code>foo</code> becomes a wrapper for the actual native
574 * method with the appended prefix "wrapped_". Note that
575 * "wrapped_" would be a poor choice of prefix since it
576 * might conceivably form the name of an existing method
577 * thus something like "$$$MyAgentWrapped$$$_" would be
578 * better but would make these examples less readable.
579 * <p>
580 * The wrapper will allow data to be collected on the native
581 * method call, but now the problem becomes linking up the
582 * wrapped method with the native implementation.
583 * That is, the method <code>wrapped_foo</code> needs to be
584 * resolved to the native implementation of <code>foo</code>,
585 * which might be:
586 * <pre>
587 * Java_somePackage_someClass_foo(JNIEnv* env, jint x)</pre>
588 * <p>
589 * This function allows the prefix to be specified and the
590 * proper resolution to occur.
591 * Specifically, when the standard resolution fails, the
592 * resolution is retried taking the prefix into consideration.
593 * There are two ways that resolution occurs, explicit
594 * resolution with the JNI function <code>RegisterNatives</code>
595 * and the normal automatic resolution. For
596 * <code>RegisterNatives</code>, the JVM will attempt this
597 * association:
598 * <pre>{@code
599 * method(foo) -> nativeImplementation(foo)
600 * }</pre>
601 * <p>
602 * When this fails, the resolution will be retried with
603 * the specified prefix prepended to the method name,
604 * yielding the correct resolution:
605 * <pre>{@code
606 * method(wrapped_foo) -> nativeImplementation(foo)
607 * }</pre>
608 * <p>
609 * For automatic resolution, the JVM will attempt:
610 * <pre>{@code
611 * method(wrapped_foo) -> nativeImplementation(wrapped_foo)
612 * }</pre>
613 * <p>
614 * When this fails, the resolution will be retried with
615 * the specified prefix deleted from the implementation name,
616 * yielding the correct resolution:
617 * <pre>{@code
618 * method(wrapped_foo) -> nativeImplementation(foo)
619 * }</pre>
620 * <p>
621 * Note that since the prefix is only used when standard
622 * resolution fails, native methods can be wrapped selectively.
623 * <p>
624 * Since each <code>ClassFileTransformer</code>
625 * can do its own transformation of the bytecodes, more
626 * than one layer of wrappers may be applied. Thus each
627 * transformer needs its own prefix. Since transformations
628 * are applied in order, the prefixes, if applied, will
629 * be applied in the same order
630 * (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}).
631 * Thus if three transformers applied
632 * wrappers, <code>foo</code> might become
633 * <code>$trans3_$trans2_$trans1_foo</code>. But if, say,
634 * the second transformer did not apply a wrapper to
635 * <code>foo</code> it would be just
636 * <code>$trans3_$trans1_foo</code>. To be able to
637 * efficiently determine the sequence of prefixes,
638 * an intermediate prefix is only applied if its non-native
639 * wrapper exists. Thus, in the last example, even though
640 * <code>$trans1_foo</code> is not a native method, the
641 * <code>$trans1_</code> prefix is applied since
642 * <code>$trans1_foo</code> exists.
643 *
644 * @param transformer
645 * The ClassFileTransformer which wraps using this prefix.
646 * @param prefix
647 * The prefix to apply to wrapped native methods when
648 * retrying a failed native method resolution. If prefix
649 * is either <code>null</code> or the empty string, then
650 * failed native method resolutions are not retried for
651 * this transformer.
652 * @throws java.lang.NullPointerException if passed a <code>null</code> transformer.
653 * @throws java.lang.UnsupportedOperationException if the current configuration of
654 * the JVM does not allow setting a native method prefix
655 * ({@link #isNativeMethodPrefixSupported} is false).
656 * @throws java.lang.IllegalArgumentException if the transformer is not registered
657 * (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}).
658 *
659 * @since 1.6
660 */
661 void
662 setNativeMethodPrefix(ClassFileTransformer transformer, String prefix);
663
664 /**
665 * Redefine a module to expand the set of modules that it reads, the set of
666 * packages that it exports or opens, or the services that it uses or
667 * provides. This method facilitates the instrumentation of code in named
668 * modules where that instrumentation requires changes to the set of modules
669 * that are read, the packages that are exported or open, or the services
670 * that are used or provided.
671 *
672 * <p> This method cannot reduce the set of modules that a module reads, nor
673 * reduce the set of packages that it exports or opens, nor reduce the set
674 * of services that it uses or provides. This method is a no-op when invoked
675 * to redefine an unnamed module. </p>
676 *
677 * <p> When expanding the services that a module uses or provides then the
678 * onus is on the agent to ensure that the service type will be accessible at
679 * each instrumentation site where the service type is used. This method
680 * does not check if the service type is a member of the module or in a
681 * package exported to the module by another module that it reads. </p>
682 *
683 * <p> The {@code extraExports} parameter is the map of additional packages
684 * to export. The {@code extraOpens} parameter is the map of additional
685 * packages to open. In both cases, the map key is the fully-qualified name
686 * of the package as defined in section 6.5.3 of
687 * <cite>The Java™ Language Specification </cite>, for example, {@code
688 * "java.lang"}. The map value is the non-empty set of modules that the
689 * package should be exported or opened to. </p>
690 *
691 * <p> The {@code extraProvides} parameter is the additional service providers
692 * for the module to provide. The map key is the service type. The map value
693 * is the non-empty list of implementation types, each of which is a member
694 * of the module and an implementation of the service. </p>
695 *
696 * <p> This method is safe for concurrent use and so allows multiple agents
697 * to instrument and update the same module at around the same time. </p>
698 *
699 * @param module the module to redefine
700 * @param extraReads the possibly-empty set of additional modules to read
701 * @param extraExports the possibly-empty map of additional packages to export
702 * @param extraOpens the possibly-empty map of additional packages to open
703 * @param extraUses the possibly-empty set of additional services to use
704 * @param extraProvides the possibly-empty map of additional services to provide
705 *
706 * @throws IllegalArgumentException
707 * If {@code extraExports} or {@code extraOpens} contains a key
708 * that is not a package in the module; if {@code extraExports} or
709 * {@code extraOpens} maps a key to an empty set; if a value in the
710 * {@code extraProvides} map contains a service provider type that
711 * is not a member of the module or an implementation of the service;
712 * or {@code extraProvides} maps a key to an empty list
713 * @throws UnmodifiableModuleException if the module cannot be modified
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 *
717 * @see #isModifiableModule(Module)
718 * @since 9
719 * @spec JPMS
720 */
721 void redefineModule(Module module,
722 Set<Module> extraReads,
723 Map<String, Set<Module>> extraExports,
724 Map<String, Set<Module>> extraOpens,
725 Set<Class<?>> extraUses,
726 Map<Class<?>, List<Class<?>>> extraProvides);
727
728 /**
729 * Tests whether a module can be modified with {@link #redefineModule
730 * redefineModule}. If a module is modifiable then this method returns
731 * {@code true}. If a module is not modifiable then this method returns
732 * {@code false}. This method always returns {@code true} when the module
733 * is an unnamed module (as redefining an unnamed module is a no-op).
734 *
735 * @param module the module to test if it can be modified
736 * @return {@code true} if the module is modifiable, otherwise {@code false}
737 * @throws NullPointerException if the module is {@code null}
738 *
739 * @since 9
740 * @spec JPMS
741 */
742 boolean isModifiableModule(Module module);
743 }