* There are two ways to obtain an instance of the
* Instrumentation interface:
*
*
When a JVM is launched in a way that indicates an agent
* class. In that case an Instrumentation instance
* is passed to the premain method of the agent class.
*
When a JVM provides a mechanism to start agents sometime
* after the JVM is launched. In that case an Instrumentation
* instance is passed to the agentmain method of the
* agent code.
* These mechanisms are described in the * {@linkplain java.lang.instrument package specification}. *
* Once an agent acquires an Instrumentation instance,
* the agent may call methods on the instance at any time.
*
* @apiNote This interface is not intended to be implemented outside of
* the java.instrument module.
*
* @since 1.5
*/
public interface Instrumentation {
/**
* Registers the supplied transformer. All future class definitions
* will be seen by the transformer, except definitions of classes upon which any
* registered transformer is dependent.
* The transformer is called when classes are loaded, when they are
* {@linkplain #redefineClasses redefined}. and if canRetransform is true,
* when they are {@linkplain #retransformClasses retransformed}.
* {@link ClassFileTransformer} defines the order of transform calls.
*
* If a transformer throws
* an exception during execution, the JVM will still call the other registered
* transformers in order. The same transformer may be added more than once,
* but it is strongly discouraged -- avoid this by creating a new instance of
* transformer class.
*
* This method is intended for use in instrumentation, as described in the
* {@linkplain Instrumentation class specification}.
*
* @param transformer the transformer to register
* @param canRetransform can this transformer's transformations be retransformed
* @throws java.lang.NullPointerException if passed a null transformer
* @throws java.lang.UnsupportedOperationException if canRetransform
* is true and the current configuration of the JVM does not allow
* retransformation ({@link #isRetransformClassesSupported} is false)
* @since 1.6
*/
void
addTransformer(ClassFileTransformer transformer, boolean canRetransform);
/**
* Registers the supplied transformer.
*
* Same as addTransformer(transformer, false).
*
* @param transformer the transformer to register
* @throws java.lang.NullPointerException if passed a null transformer
* @see #addTransformer(ClassFileTransformer,boolean)
*/
void
addTransformer(ClassFileTransformer transformer);
/**
* Unregisters the supplied transformer. Future class definitions will
* not be shown to the transformer. Removes the most-recently-added matching
* instance of the transformer. Due to the multi-threaded nature of
* class loading, it is possible for a transformer to receive calls
* after it has been removed. Transformers should be written defensively
* to expect this situation.
*
* @param transformer the transformer to unregister
* @return true if the transformer was found and removed, false if the
* transformer was not found
* @throws java.lang.NullPointerException if passed a null transformer
*/
boolean
removeTransformer(ClassFileTransformer transformer);
/**
* Returns whether or not the current JVM configuration supports retransformation
* of classes.
* The ability to retransform an already loaded class is an optional capability
* of a JVM.
* Retransformation will only be supported if the
* Can-Retransform-Classes manifest attribute is set to
* true in the agent JAR file (as described in the
* {@linkplain java.lang.instrument package specification}) and the JVM supports
* this capability.
* During a single instantiation of a single JVM, multiple calls to this
* method will always return the same answer.
* @return true if the current JVM configuration supports retransformation of
* classes, false if not.
* @see #retransformClasses
* @since 1.6
*/
boolean
isRetransformClassesSupported();
/**
* Retransform the supplied set of classes.
*
*
* This function facilitates the instrumentation * of already loaded classes. * When classes are initially loaded or when they are * {@linkplain #redefineClasses redefined}, * the initial class file bytes can be transformed with the * {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer}. * This function reruns the transformation process * (whether or not a transformation has previously occurred). * This retransformation follows these steps: *
canRetransform
* false, the bytes returned by
* {@link ClassFileTransformer#transform(Module,ClassLoader,String,Class,ProtectionDomain,byte[])
* transform} during the last class load or redefine are
* reused as the output of the transformation; note that this is
* equivalent to reapplying the previous transformation, unaltered;
* except that {@code transform} method is not called.
* canRetransform
* true, the
* {@link ClassFileTransformer#transform(Module,ClassLoader,String,Class,ProtectionDomain,byte[])
* transform} method is called in these transformers
* * * The order of transformation is described in {@link ClassFileTransformer}. * This same order is used in the automatic reapplication of * retransformation incapable transforms. *
* * The initial class file bytes represent the bytes passed to * {@link java.lang.ClassLoader#defineClass ClassLoader.defineClass} or * {@link #redefineClasses redefineClasses} * (before any transformations * were applied), however they might not exactly match them. * The constant pool might not have the same layout or contents. * The constant pool may have more or fewer entries. * Constant pool entries may be in a different order; however, * constant pool indices in the bytecodes of methods will correspond. * Some attributes may not be present. * Where order is not meaningful, for example the order of methods, * order might not be preserved. * *
* This method operates on * a set in order to allow interdependent changes to more than one class at the same time * (a retransformation of class A can require a retransformation of class B). * *
* If a retransformed method has active stack frames, those active frames continue to * run the bytecodes of the original method. * The retransformed method will be used on new invokes. * *
* This method does not cause any initialization except that which would occur * under the customary JVM semantics. In other words, redefining a class * does not cause its initializers to be run. The values of static variables * will remain as they were prior to the call. * *
* Instances of the retransformed class are not affected. * *
* The supported class file changes are described in * JVM TI RetransformClasses. * The class file bytes are not checked, verified and installed * until after the transformations have been applied, if the resultant bytes are in * error this method will throw an exception. * *
* If this method throws an exception, no classes have been retransformed. *
* This method is intended for use in instrumentation, as described in the
* {@linkplain Instrumentation class specification}.
*
* @param classes array of classes to retransform;
* a zero-length array is allowed, in this case, this method does nothing
* @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified
* ({@link #isModifiableClass} would return false)
* @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow
* retransformation ({@link #isRetransformClassesSupported} is false) or the retransformation attempted
* to make unsupported changes
* @throws java.lang.ClassFormatError if the data did not contain a valid class
* @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class
* @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported
* @throws java.lang.ClassCircularityError if the new classes contain a circularity
* @throws java.lang.LinkageError if a linkage error occurs
* @throws java.lang.NullPointerException if the supplied classes array or any of its components
* is null.
*
* @see #isRetransformClassesSupported
* @see #addTransformer
* @see java.lang.instrument.ClassFileTransformer
* @since 1.6
*/
void
retransformClasses(Class... classes) throws UnmodifiableClassException;
/**
* Returns whether or not the current JVM configuration supports redefinition
* of classes.
* The ability to redefine an already loaded class is an optional capability
* of a JVM.
* Redefinition will only be supported if the
* Can-Redefine-Classes manifest attribute is set to
* true in the agent JAR file (as described in the
* {@linkplain java.lang.instrument package specification}) and the JVM supports
* this capability.
* During a single instantiation of a single JVM, multiple calls to this
* method will always return the same answer.
* @return true if the current JVM configuration supports redefinition of classes,
* false if not.
* @see #redefineClasses
*/
boolean
isRedefineClassesSupported();
/**
* Redefine the supplied set of classes using the supplied class files.
*
*
* This method is used to replace the definition of a class without reference * to the existing class file bytes, as one might do when recompiling from source * for fix-and-continue debugging. * Where the existing class file bytes are to be transformed (for * example in bytecode instrumentation) * {@link #retransformClasses retransformClasses} * should be used. * *
* This method operates on * a set in order to allow interdependent changes to more than one class at the same time * (a redefinition of class A can require a redefinition of class B). * *
* If a redefined method has active stack frames, those active frames continue to * run the bytecodes of the original method. * The redefined method will be used on new invokes. * *
* This method does not cause any initialization except that which would occur * under the customary JVM semantics. In other words, redefining a class * does not cause its initializers to be run. The values of static variables * will remain as they were prior to the call. * *
* Instances of the redefined class are not affected. * *
* The supported class file changes are described in * JVM TI RedefineClasses. * The class file bytes are not checked, verified and installed * until after the transformations have been applied, if the resultant bytes are in * error this method will throw an exception. * *
* If this method throws an exception, no classes have been redefined. *
* This method is intended for use in instrumentation, as described in the
* {@linkplain Instrumentation class specification}.
*
* @param definitions array of classes to redefine with corresponding definitions;
* a zero-length array is allowed, in this case, this method does nothing
* @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified
* ({@link #isModifiableClass} would return false)
* @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow
* redefinition ({@link #isRedefineClassesSupported} is false) or the redefinition attempted
* to make unsupported changes
* @throws java.lang.ClassFormatError if the data did not contain a valid class
* @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class
* @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported
* @throws java.lang.ClassCircularityError if the new classes contain a circularity
* @throws java.lang.LinkageError if a linkage error occurs
* @throws java.lang.NullPointerException if the supplied definitions array or any of its components
* is null
* @throws java.lang.ClassNotFoundException Can never be thrown (present for compatibility reasons only)
*
* @see #isRedefineClassesSupported
* @see #addTransformer
* @see java.lang.instrument.ClassFileTransformer
*/
void
redefineClasses(ClassDefinition... definitions)
throws ClassNotFoundException, UnmodifiableClassException;
/**
* Tests whether a class is modifiable by
* {@linkplain #retransformClasses retransformation}
* or {@linkplain #redefineClasses redefinition}.
* If a class is modifiable then this method returns true.
* If a class is not modifiable then this method returns false.
*
* For a class to be retransformed, {@link #isRetransformClassesSupported} must also be true.
* But the value of isRetransformClassesSupported() does not influence the value
* returned by this function.
* For a class to be redefined, {@link #isRedefineClassesSupported} must also be true.
* But the value of isRedefineClassesSupported() does not influence the value
* returned by this function.
*
* Primitive classes (for example, java.lang.Integer.TYPE)
* and array classes are never modifiable.
*
* @param theClass the class to check for being modifiable
* @return whether or not the argument class is modifiable
* @throws java.lang.NullPointerException if the specified class is null.
*
* @see #retransformClasses
* @see #isRetransformClassesSupported
* @see #redefineClasses
* @see #isRedefineClassesSupported
* @since 1.6
*/
boolean
isModifiableClass(Class theClass);
/**
* Returns an array of all classes currently loaded by the JVM.
* The returned array includes all classes and interfaces, including
* {@linkplain Class#isHidden hidden classes or interfaces}, and array classes
* of all types.
*
* @return an array containing all the classes loaded by the JVM, zero-length if there are none
*/
@SuppressWarnings("rawtypes")
Class[]
getAllLoadedClasses();
/**
* Returns an array of all classes which {@code loader} can find by name
* via {@link ClassLoader#loadClass(String, boolean) ClassLoader::loadClass},
* {@link Class#forName(String) Class::forName} and bytecode linkage.
* That is, all classes for which {@code loader} has been recorded as
* an initiating loader. If the supplied {@code loader} is {@code null},
* classes that the bootstrap class loader can find by name are returned.
*
* The returned array does not include {@linkplain Class#isHidden()
* hidden classes or interfaces} or array classes whose
* {@linkplain Class#componentType() element type} is a
* {@linkplain Class#isHidden() hidden class or interface}.
* as they cannot be discovered by any class loader.
*
* @param loader the loader whose initiated class list will be returned
* @return an array containing all classes which {@code loader} can find by name;
* zero-length if there are none
*/
@SuppressWarnings("rawtypes")
Class[]
getInitiatedClasses(ClassLoader loader);
/**
* Returns an implementation-specific approximation of the amount of storage consumed by
* the specified object. The result may include some or all of the object's overhead,
* and thus is useful for comparison within an implementation but not between implementations.
*
* The estimate may change during a single invocation of the JVM.
*
* @param objectToSize the object to size
* @return an implementation-specific approximation of the amount of storage consumed by the specified object
* @throws java.lang.NullPointerException if the supplied Object is null.
*/
long
getObjectSize(Object objectToSize);
/**
* Specifies a JAR file with instrumentation classes to be defined by the
* bootstrap class loader.
*
*
When the virtual machine's built-in class loader, known as the "bootstrap * class loader", unsuccessfully searches for a class, the entries in the {@link * java.util.jar.JarFile JAR file} will be searched as well. * *
This method may be used multiple times to add multiple JAR files to be * searched in the order that this method was invoked. * *
The agent should take care to ensure that the JAR does not contain any
* classes or resources other than those to be defined by the bootstrap
* class loader for the purpose of instrumentation.
* Failure to observe this warning could result in unexpected
* behavior that is difficult to diagnose. For example, suppose there is a
* loader L, and L's parent for delegation is the bootstrap class loader.
* Furthermore, a method in class C, a class defined by L, makes reference to
* a non-public accessor class C$1. If the JAR file contains a class C$1 then
* the delegation to the bootstrap class loader will cause C$1 to be defined
* by the bootstrap class loader. In this example an IllegalAccessError
* will be thrown that may cause the application to fail. One approach to
* avoiding these types of issues, is to use a unique package name for the
* instrumentation classes.
*
*
* The Java Virtual Machine Specification
* specifies that a subsequent attempt to resolve a symbolic
* reference that the Java virtual machine has previously unsuccessfully attempted
* to resolve always fails with the same error that was thrown as a result of the
* initial resolution attempt. Consequently, if the JAR file contains an entry
* that corresponds to a class for which the Java virtual machine has
* unsuccessfully attempted to resolve a reference, then subsequent attempts to
* resolve that reference will fail with the same error as the initial attempt.
*
* @param jarfile
* The JAR file to be searched when the bootstrap class loader
* unsuccessfully searches for a class.
*
* @throws NullPointerException
* If jarfile is null.
*
* @see #appendToSystemClassLoaderSearch
* @see java.lang.ClassLoader
* @see java.util.jar.JarFile
*
* @since 1.6
*/
void
appendToBootstrapClassLoaderSearch(JarFile jarfile);
/**
* Specifies a JAR file with instrumentation classes to be defined by the
* system class loader.
*
* When the system class loader for delegation (see
* {@link java.lang.ClassLoader#getSystemClassLoader getSystemClassLoader()})
* unsuccessfully searches for a class, the entries in the {@link
* java.util.jar.JarFile JarFile} will be searched as well.
*
*
This method may be used multiple times to add multiple JAR files to be * searched in the order that this method was invoked. * *
The agent should take care to ensure that the JAR does not contain any * classes or resources other than those to be defined by the system class * loader for the purpose of instrumentation. * Failure to observe this warning could result in unexpected * behavior that is difficult to diagnose (see * {@link #appendToBootstrapClassLoaderSearch * appendToBootstrapClassLoaderSearch}). * *
The system class loader supports adding a JAR file to be searched if
* it implements a method named appendToClassPathForInstrumentation
* which takes a single parameter of type java.lang.String. The
* method is not required to have public access. The name of
* the JAR file is obtained by invoking the {@link java.util.zip.ZipFile#getName
* getName()} method on the jarfile and this is provided as the
* parameter to the appendToClassPathForInstrumentation method.
*
*
* The Java Virtual Machine Specification * specifies that a subsequent attempt to resolve a symbolic * reference that the Java virtual machine has previously unsuccessfully attempted * to resolve always fails with the same error that was thrown as a result of the * initial resolution attempt. Consequently, if the JAR file contains an entry * that corresponds to a class for which the Java virtual machine has * unsuccessfully attempted to resolve a reference, then subsequent attempts to * resolve that reference will fail with the same error as the initial attempt. * *
This method does not change the value of java.class.path
* {@link java.lang.System#getProperties system property}.
*
* @param jarfile
* The JAR file to be searched when the system class loader
* unsuccessfully searches for a class.
*
* @throws UnsupportedOperationException
* If the system class loader does not support appending a
* a JAR file to be searched.
*
* @throws NullPointerException
* If jarfile is null.
*
* @see #appendToBootstrapClassLoaderSearch
* @see java.lang.ClassLoader#getSystemClassLoader
* @see java.util.jar.JarFile
* @since 1.6
*/
void
appendToSystemClassLoaderSearch(JarFile jarfile);
/**
* Returns whether the current JVM configuration supports
* {@linkplain #setNativeMethodPrefix(ClassFileTransformer,String)
* setting a native method prefix}.
* The ability to set a native method prefix is an optional
* capability of a JVM.
* Setting a native method prefix will only be supported if the
* Can-Set-Native-Method-Prefix manifest attribute is set to
* true in the agent JAR file (as described in the
* {@linkplain java.lang.instrument package specification}) and the JVM supports
* this capability.
* During a single instantiation of a single JVM, multiple
* calls to this method will always return the same answer.
* @return true if the current JVM configuration supports
* setting a native method prefix, false if not.
* @see #setNativeMethodPrefix
* @since 1.6
*/
boolean
isNativeMethodPrefixSupported();
/**
* This method modifies the failure handling of
* native method resolution by allowing retry
* with a prefix applied to the name.
* When used with the
* {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer},
* it enables native methods to be
* instrumented.
*
* Since native methods cannot be directly instrumented * (they have no bytecodes), they must be wrapped with * a non-native method which can be instrumented. * For example, if we had: *
* native boolean foo(int x);
* * We could transform the class file (with the * ClassFileTransformer during the initial definition * of the class) so that this becomes: *
* boolean foo(int x) {
* ... record entry to foo ...
* return wrapped_foo(x);
* }
*
* native boolean wrapped_foo(int x);
*
* Where foo becomes a wrapper for the actual native
* method with the appended prefix "wrapped_". Note that
* "wrapped_" would be a poor choice of prefix since it
* might conceivably form the name of an existing method
* thus something like "$$$MyAgentWrapped$$$_" would be
* better but would make these examples less readable.
*
* The wrapper will allow data to be collected on the native
* method call, but now the problem becomes linking up the
* wrapped method with the native implementation.
* That is, the method wrapped_foo needs to be
* resolved to the native implementation of foo,
* which might be:
*
* Java_somePackage_someClass_foo(JNIEnv* env, jint x)
*
* This function allows the prefix to be specified and the
* proper resolution to occur.
* Specifically, when the standard resolution fails, the
* resolution is retried taking the prefix into consideration.
* There are two ways that resolution occurs, explicit
* resolution with the JNI function RegisterNatives
* and the normal automatic resolution. For
* RegisterNatives, the JVM will attempt this
* association:
*
{@code
* method(foo) -> nativeImplementation(foo)
* }
* * When this fails, the resolution will be retried with * the specified prefix prepended to the method name, * yielding the correct resolution: *
{@code
* method(wrapped_foo) -> nativeImplementation(foo)
* }
* * For automatic resolution, the JVM will attempt: *
{@code
* method(wrapped_foo) -> nativeImplementation(wrapped_foo)
* }
* * When this fails, the resolution will be retried with * the specified prefix deleted from the implementation name, * yielding the correct resolution: *
{@code
* method(wrapped_foo) -> nativeImplementation(foo)
* }
* * Note that since the prefix is only used when standard * resolution fails, native methods can be wrapped selectively. *
* Since each ClassFileTransformer
* can do its own transformation of the bytecodes, more
* than one layer of wrappers may be applied. Thus each
* transformer needs its own prefix. Since transformations
* are applied in order, the prefixes, if applied, will
* be applied in the same order
* (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}).
* Thus if three transformers applied
* wrappers, foo might become
* $trans3_$trans2_$trans1_foo. But if, say,
* the second transformer did not apply a wrapper to
* foo it would be just
* $trans3_$trans1_foo. To be able to
* efficiently determine the sequence of prefixes,
* an intermediate prefix is only applied if its non-native
* wrapper exists. Thus, in the last example, even though
* $trans1_foo is not a native method, the
* $trans1_ prefix is applied since
* $trans1_foo exists.
*
* @param transformer
* The ClassFileTransformer which wraps using this prefix.
* @param prefix
* The prefix to apply to wrapped native methods when
* retrying a failed native method resolution. If prefix
* is either null or the empty string, then
* failed native method resolutions are not retried for
* this transformer.
* @throws java.lang.NullPointerException if passed a null transformer.
* @throws java.lang.UnsupportedOperationException if the current configuration of
* the JVM does not allow setting a native method prefix
* ({@link #isNativeMethodPrefixSupported} is false).
* @throws java.lang.IllegalArgumentException if the transformer is not registered
* (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}).
*
* @since 1.6
*/
void
setNativeMethodPrefix(ClassFileTransformer transformer, String prefix);
/**
* Redefine a module to expand the set of modules that it reads, the set of
* packages that it exports or opens, or the services that it uses or
* provides. This method facilitates the instrumentation of code in named
* modules where that instrumentation requires changes to the set of modules
* that are read, the packages that are exported or open, or the services
* that are used or provided.
*
*
This method cannot reduce the set of modules that a module reads, nor * reduce the set of packages that it exports or opens, nor reduce the set * of services that it uses or provides. This method is a no-op when invoked * to redefine an unnamed module.
* *When expanding the services that a module uses or provides then the * onus is on the agent to ensure that the service type will be accessible at * each instrumentation site where the service type is used. This method * does not check if the service type is a member of the module or in a * package exported to the module by another module that it reads.
* *The {@code extraExports} parameter is the map of additional packages * to export. The {@code extraOpens} parameter is the map of additional * packages to open. In both cases, the map key is the fully-qualified name * of the package as defined in section 6.5.3 of * The Java Language Specification , for example, {@code * "java.lang"}. The map value is the non-empty set of modules that the * package should be exported or opened to.
* *The {@code extraProvides} parameter is the additional service providers * for the module to provide. The map key is the service type. The map value * is the non-empty list of implementation types, each of which is a member * of the module and an implementation of the service.
* *This method is safe for concurrent use and so allows multiple agents * to instrument and update the same module at around the same time.
* * @param module the module to redefine * @param extraReads the possibly-empty set of additional modules to read * @param extraExports the possibly-empty map of additional packages to export * @param extraOpens the possibly-empty map of additional packages to open * @param extraUses the possibly-empty set of additional services to use * @param extraProvides the possibly-empty map of additional services to provide * * @throws IllegalArgumentException * If {@code extraExports} or {@code extraOpens} contains a key * that is not a package in the module; if {@code extraExports} or * {@code extraOpens} maps a key to an empty set; if a value in the * {@code extraProvides} map contains a service provider type that * is not a member of the module or an implementation of the service; * or {@code extraProvides} maps a key to an empty list * @throws UnmodifiableModuleException if the module cannot be modified * @throws NullPointerException if any of the arguments are {@code null} or * any of the Sets or Maps contains a {@code null} key or value * * @see #isModifiableModule(Module) * @since 9 * @spec JPMS */ void redefineModule(Module module, Set