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