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 }