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> or
 230      * <code>NestMembers</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> or
 321      * <code>NestMembers</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&trade; 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&trade; 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&trade; 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 }