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 * <p> 392 * A class or interface creation can be triggered by one of the following: 393 * <ul> 394 * <li>by loading and deriving a class from a `class` file representation 395 * using class loader (see JVMS {@jvms 5.3}). 396 * <li>by invoking {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, java.lang.invoke.MethodHandles.Lookup.ClassOption...) 397 * Lookup::defineHiddenClass} that creates a {@link Class#isHidden 398 * hidden class or interface} from a {@code class} file representation. 399 * <li>by invoking methods in certain reflection APIs such as 400 * {@link Class#forName(String) Class::forName}. 401 * </ul> 402 * <p> 403 * An array class is created directly by Java virtual machine. An array 404 * class creation can be triggered by using class loaders or by invoking 405 * methods in certain reflection APIs such as 406 * {@link java.lang.reflect.Array#newInstance(Class, int) Array::newInstance} 407 * and {@link Class#arrayType() Class::arrayType}. 408 * <p> 409 * The returned array includes all classes and interfaces, including 410 * {@link Class#isHidden hidden classes or interfaces}, and array classes 411 * of all types. 412 * 413 * @return an array containing all the classes loaded by the JVM, zero-length if there are none 414 */ 415 @SuppressWarnings("rawtypes") 416 Class[] 417 getAllLoadedClasses(); 418 419 /** 420 * Returns an array of all classes which {@code loader} can find by name 421 * via {@link ClassLoader#loadClass(String, boolean) ClassLoader::loadClass}, 422 * {@link Class#forName(String) Class::forName} and bytecode linkage. 423 * That is, {@code loader} has been recorded as an initiating loader 424 * of these classes. If the supplied {@code loader} is {@code null}, 425 * classes that the bootstrap class loader can find by name are returned. 426 * 427 * <p> 428 * The returned array does not include {@link Class#isHidden() 429 * <em>hidden</em>} classes or interfaces that are created by the invocation of 430 * {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, java.lang.invoke.MethodHandles.Lookup.ClassOption...) 431 * Lookup::defineHiddenClass} because: 432 * <ul> 433 * <li>A hidden class or interface cannot be referenced by the constant pools 434 * of other classes and interfaces. 435 * <li>A hidden class or interface cannot be discovered by any class loader. 436 * </ul> 437 * In addition, the returned array does not include array classes whose 438 * {@linkplain Class#componentType() element type} is a 439 * {@link Class#isHidden() hidden class or interface} as they cannot 440 * be discovered by {@code loader}. 441 * 442 * @param loader the loader whose initiated class list will be returned 443 * @return an array containing all classes which {@code loader} can find by name; 444 * zero-length if there are none 445 */ 446 @SuppressWarnings("rawtypes") 447 Class[] 448 getInitiatedClasses(ClassLoader loader); 449 450 /** 451 * Returns an implementation-specific approximation of the amount of storage consumed by 452 * the specified object. The result may include some or all of the object's overhead, 453 * and thus is useful for comparison within an implementation but not between implementations. 454 * 455 * The estimate may change during a single invocation of the JVM. 456 * 457 * @param objectToSize the object to size 458 * @return an implementation-specific approximation of the amount of storage consumed by the specified object 459 * @throws java.lang.NullPointerException if the supplied Object is <code>null</code>. 460 */ 461 long 462 getObjectSize(Object objectToSize); 463 464 465 /** 466 * Specifies a JAR file with instrumentation classes to be defined by the 467 * bootstrap class loader. 468 * 469 * <p> When the virtual machine's built-in class loader, known as the "bootstrap 470 * class loader", unsuccessfully searches for a class, the entries in the {@link 471 * java.util.jar.JarFile JAR file} will be searched as well. 472 * 473 * <p> This method may be used multiple times to add multiple JAR files to be 474 * searched in the order that this method was invoked. 475 * 476 * <p> The agent should take care to ensure that the JAR does not contain any 477 * classes or resources other than those to be defined by the bootstrap 478 * class loader for the purpose of instrumentation. 479 * Failure to observe this warning could result in unexpected 480 * behavior that is difficult to diagnose. For example, suppose there is a 481 * loader L, and L's parent for delegation is the bootstrap class loader. 482 * Furthermore, a method in class C, a class defined by L, makes reference to 483 * a non-public accessor class C$1. If the JAR file contains a class C$1 then 484 * the delegation to the bootstrap class loader will cause C$1 to be defined 485 * by the bootstrap class loader. In this example an <code>IllegalAccessError</code> 486 * will be thrown that may cause the application to fail. One approach to 487 * avoiding these types of issues, is to use a unique package name for the 488 * instrumentation classes. 489 * 490 * <p> 491 * <cite>The Java™ Virtual Machine Specification</cite> 492 * specifies that a subsequent attempt to resolve a symbolic 493 * reference that the Java virtual machine has previously unsuccessfully attempted 494 * to resolve always fails with the same error that was thrown as a result of the 495 * initial resolution attempt. Consequently, if the JAR file contains an entry 496 * that corresponds to a class for which the Java virtual machine has 497 * unsuccessfully attempted to resolve a reference, then subsequent attempts to 498 * resolve that reference will fail with the same error as the initial attempt. 499 * 500 * @param jarfile 501 * The JAR file to be searched when the bootstrap class loader 502 * unsuccessfully searches for a class. 503 * 504 * @throws NullPointerException 505 * If <code>jarfile</code> is <code>null</code>. 506 * 507 * @see #appendToSystemClassLoaderSearch 508 * @see java.lang.ClassLoader 509 * @see java.util.jar.JarFile 510 * 511 * @since 1.6 512 */ 513 void 514 appendToBootstrapClassLoaderSearch(JarFile jarfile); 515 516 /** 517 * Specifies a JAR file with instrumentation classes to be defined by the 518 * system class loader. 519 * 520 * When the system class loader for delegation (see 521 * {@link java.lang.ClassLoader#getSystemClassLoader getSystemClassLoader()}) 522 * unsuccessfully searches for a class, the entries in the {@link 523 * java.util.jar.JarFile JarFile} will be searched as well. 524 * 525 * <p> This method may be used multiple times to add multiple JAR files to be 526 * searched in the order that this method was invoked. 527 * 528 * <p> The agent should take care to ensure that the JAR does not contain any 529 * classes or resources other than those to be defined by the system class 530 * loader for the purpose of instrumentation. 531 * Failure to observe this warning could result in unexpected 532 * behavior that is difficult to diagnose (see 533 * {@link #appendToBootstrapClassLoaderSearch 534 * appendToBootstrapClassLoaderSearch}). 535 * 536 * <p> The system class loader supports adding a JAR file to be searched if 537 * it implements a method named <code>appendToClassPathForInstrumentation</code> 538 * which takes a single parameter of type <code>java.lang.String</code>. The 539 * method is not required to have <code>public</code> access. The name of 540 * the JAR file is obtained by invoking the {@link java.util.zip.ZipFile#getName 541 * getName()} method on the <code>jarfile</code> and this is provided as the 542 * parameter to the <code>appendToClassPathForInstrumentation</code> method. 543 * 544 * <p> 545 * <cite>The Java™ Virtual Machine Specification</cite> 546 * specifies that a subsequent attempt to resolve a symbolic 547 * reference that the Java virtual machine has previously unsuccessfully attempted 548 * to resolve always fails with the same error that was thrown as a result of the 549 * initial resolution attempt. Consequently, if the JAR file contains an entry 550 * that corresponds to a class for which the Java virtual machine has 551 * unsuccessfully attempted to resolve a reference, then subsequent attempts to 552 * resolve that reference will fail with the same error as the initial attempt. 553 * 554 * <p> This method does not change the value of <code>java.class.path</code> 555 * {@link java.lang.System#getProperties system property}. 556 * 557 * @param jarfile 558 * The JAR file to be searched when the system class loader 559 * unsuccessfully searches for a class. 560 * 561 * @throws UnsupportedOperationException 562 * If the system class loader does not support appending a 563 * a JAR file to be searched. 564 * 565 * @throws NullPointerException 566 * If <code>jarfile</code> is <code>null</code>. 567 * 568 * @see #appendToBootstrapClassLoaderSearch 569 * @see java.lang.ClassLoader#getSystemClassLoader 570 * @see java.util.jar.JarFile 571 * @since 1.6 572 */ 573 void 574 appendToSystemClassLoaderSearch(JarFile jarfile); 575 576 /** 577 * Returns whether the current JVM configuration supports 578 * {@linkplain #setNativeMethodPrefix(ClassFileTransformer,String) 579 * setting a native method prefix}. 580 * The ability to set a native method prefix is an optional 581 * capability of a JVM. 582 * Setting a native method prefix will only be supported if the 583 * <code>Can-Set-Native-Method-Prefix</code> manifest attribute is set to 584 * <code>true</code> in the agent JAR file (as described in the 585 * {@linkplain java.lang.instrument package specification}) and the JVM supports 586 * this capability. 587 * During a single instantiation of a single JVM, multiple 588 * calls to this method will always return the same answer. 589 * @return true if the current JVM configuration supports 590 * setting a native method prefix, false if not. 591 * @see #setNativeMethodPrefix 592 * @since 1.6 593 */ 594 boolean 595 isNativeMethodPrefixSupported(); 596 597 /** 598 * This method modifies the failure handling of 599 * native method resolution by allowing retry 600 * with a prefix applied to the name. 601 * When used with the 602 * {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer}, 603 * it enables native methods to be 604 * instrumented. 605 * <p> 606 * Since native methods cannot be directly instrumented 607 * (they have no bytecodes), they must be wrapped with 608 * a non-native method which can be instrumented. 609 * For example, if we had: 610 * <pre> 611 * native boolean foo(int x);</pre> 612 * <p> 613 * We could transform the class file (with the 614 * ClassFileTransformer during the initial definition 615 * of the class) so that this becomes: 616 * <pre> 617 * boolean foo(int x) { 618 * <i>... record entry to foo ...</i> 619 * return wrapped_foo(x); 620 * } 621 * 622 * native boolean wrapped_foo(int x);</pre> 623 * <p> 624 * Where <code>foo</code> becomes a wrapper for the actual native 625 * method with the appended prefix "wrapped_". Note that 626 * "wrapped_" would be a poor choice of prefix since it 627 * might conceivably form the name of an existing method 628 * thus something like "$$$MyAgentWrapped$$$_" would be 629 * better but would make these examples less readable. 630 * <p> 631 * The wrapper will allow data to be collected on the native 632 * method call, but now the problem becomes linking up the 633 * wrapped method with the native implementation. 634 * That is, the method <code>wrapped_foo</code> needs to be 635 * resolved to the native implementation of <code>foo</code>, 636 * which might be: 637 * <pre> 638 * Java_somePackage_someClass_foo(JNIEnv* env, jint x)</pre> 639 * <p> 640 * This function allows the prefix to be specified and the 641 * proper resolution to occur. 642 * Specifically, when the standard resolution fails, the 643 * resolution is retried taking the prefix into consideration. 644 * There are two ways that resolution occurs, explicit 645 * resolution with the JNI function <code>RegisterNatives</code> 646 * and the normal automatic resolution. For 647 * <code>RegisterNatives</code>, the JVM will attempt this 648 * association: 649 * <pre>{@code 650 * method(foo) -> nativeImplementation(foo) 651 * }</pre> 652 * <p> 653 * When this fails, the resolution will be retried with 654 * the specified prefix prepended to the method name, 655 * yielding the correct resolution: 656 * <pre>{@code 657 * method(wrapped_foo) -> nativeImplementation(foo) 658 * }</pre> 659 * <p> 660 * For automatic resolution, the JVM will attempt: 661 * <pre>{@code 662 * method(wrapped_foo) -> nativeImplementation(wrapped_foo) 663 * }</pre> 664 * <p> 665 * When this fails, the resolution will be retried with 666 * the specified prefix deleted from the implementation name, 667 * yielding the correct resolution: 668 * <pre>{@code 669 * method(wrapped_foo) -> nativeImplementation(foo) 670 * }</pre> 671 * <p> 672 * Note that since the prefix is only used when standard 673 * resolution fails, native methods can be wrapped selectively. 674 * <p> 675 * Since each <code>ClassFileTransformer</code> 676 * can do its own transformation of the bytecodes, more 677 * than one layer of wrappers may be applied. Thus each 678 * transformer needs its own prefix. Since transformations 679 * are applied in order, the prefixes, if applied, will 680 * be applied in the same order 681 * (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}). 682 * Thus if three transformers applied 683 * wrappers, <code>foo</code> might become 684 * <code>$trans3_$trans2_$trans1_foo</code>. But if, say, 685 * the second transformer did not apply a wrapper to 686 * <code>foo</code> it would be just 687 * <code>$trans3_$trans1_foo</code>. To be able to 688 * efficiently determine the sequence of prefixes, 689 * an intermediate prefix is only applied if its non-native 690 * wrapper exists. Thus, in the last example, even though 691 * <code>$trans1_foo</code> is not a native method, the 692 * <code>$trans1_</code> prefix is applied since 693 * <code>$trans1_foo</code> exists. 694 * 695 * @param transformer 696 * The ClassFileTransformer which wraps using this prefix. 697 * @param prefix 698 * The prefix to apply to wrapped native methods when 699 * retrying a failed native method resolution. If prefix 700 * is either <code>null</code> or the empty string, then 701 * failed native method resolutions are not retried for 702 * this transformer. 703 * @throws java.lang.NullPointerException if passed a <code>null</code> transformer. 704 * @throws java.lang.UnsupportedOperationException if the current configuration of 705 * the JVM does not allow setting a native method prefix 706 * ({@link #isNativeMethodPrefixSupported} is false). 707 * @throws java.lang.IllegalArgumentException if the transformer is not registered 708 * (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}). 709 * 710 * @since 1.6 711 */ 712 void 713 setNativeMethodPrefix(ClassFileTransformer transformer, String prefix); 714 715 /** 716 * Redefine a module to expand the set of modules that it reads, the set of 717 * packages that it exports or opens, or the services that it uses or 718 * provides. This method facilitates the instrumentation of code in named 719 * modules where that instrumentation requires changes to the set of modules 720 * that are read, the packages that are exported or open, or the services 721 * that are used or provided. 722 * 723 * <p> This method cannot reduce the set of modules that a module reads, nor 724 * reduce the set of packages that it exports or opens, nor reduce the set 725 * of services that it uses or provides. This method is a no-op when invoked 726 * to redefine an unnamed module. </p> 727 * 728 * <p> When expanding the services that a module uses or provides then the 729 * onus is on the agent to ensure that the service type will be accessible at 730 * each instrumentation site where the service type is used. This method 731 * does not check if the service type is a member of the module or in a 732 * package exported to the module by another module that it reads. </p> 733 * 734 * <p> The {@code extraExports} parameter is the map of additional packages 735 * to export. The {@code extraOpens} parameter is the map of additional 736 * packages to open. In both cases, the map key is the fully-qualified name 737 * of the package as defined in section 6.5.3 of 738 * <cite>The Java™ Language Specification </cite>, for example, {@code 739 * "java.lang"}. The map value is the non-empty set of modules that the 740 * package should be exported or opened to. </p> 741 * 742 * <p> The {@code extraProvides} parameter is the additional service providers 743 * for the module to provide. The map key is the service type. The map value 744 * is the non-empty list of implementation types, each of which is a member 745 * of the module and an implementation of the service. </p> 746 * 747 * <p> This method is safe for concurrent use and so allows multiple agents 748 * to instrument and update the same module at around the same time. </p> 749 * 750 * @param module the module to redefine 751 * @param extraReads the possibly-empty set of additional modules to read 752 * @param extraExports the possibly-empty map of additional packages to export 753 * @param extraOpens the possibly-empty map of additional packages to open 754 * @param extraUses the possibly-empty set of additional services to use 755 * @param extraProvides the possibly-empty map of additional services to provide 756 * 757 * @throws IllegalArgumentException 758 * If {@code extraExports} or {@code extraOpens} contains a key 759 * that is not a package in the module; if {@code extraExports} or 760 * {@code extraOpens} maps a key to an empty set; if a value in the 761 * {@code extraProvides} map contains a service provider type that 762 * is not a member of the module or an implementation of the service; 763 * or {@code extraProvides} maps a key to an empty list 764 * @throws UnmodifiableModuleException if the module cannot be modified 765 * @throws NullPointerException if any of the arguments are {@code null} or 766 * any of the Sets or Maps contains a {@code null} key or value 767 * 768 * @see #isModifiableModule(Module) 769 * @since 9 770 * @spec JPMS 771 */ 772 void redefineModule(Module module, 773 Set<Module> extraReads, 774 Map<String, Set<Module>> extraExports, 775 Map<String, Set<Module>> extraOpens, 776 Set<Class<?>> extraUses, 777 Map<Class<?>, List<Class<?>>> extraProvides); 778 779 /** 780 * Tests whether a module can be modified with {@link #redefineModule 781 * redefineModule}. If a module is modifiable then this method returns 782 * {@code true}. If a module is not modifiable then this method returns 783 * {@code false}. This method always returns {@code true} when the module 784 * is an unnamed module (as redefining an unnamed module is a no-op). 785 * 786 * @param module the module to test if it can be modified 787 * @return {@code true} if the module is modifiable, otherwise {@code false} 788 * @throws NullPointerException if the module is {@code null} 789 * 790 * @since 9 791 * @spec JPMS 792 */ 793 boolean isModifiableModule(Module module); 794 }