public interface Instrumentation
This class provides services needed to instrument Java programming language code. Instrumentation is the addition of byte-codes to methods for the purpose of gathering data to be utilized by tools. Since the changes are purely additive, these tools do not modify application state or behavior. Examples of such benign tools include monitoring agents, profilers, coverage analyzers, and event loggers.
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
the
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
the
Instrumentation instance is passed to the agentmain method of the agent code.
These mechanisms are described in the package specification .
Once an agent acquires
an
the
Instrumentation instance, the agent may call methods on the instance at any time.
Method Summary | |
---|---|
void |
addTransformer
(
ClassFileTransformer
transformer) Registers the supplied transformer. |
void |
addTransformer
(
ClassFileTransformer
transformer, boolean canRetransform) Registers the supplied transformer. |
void |
appendToBootstrapClassLoaderSearch
(
JarFile
jarfile) Specifies a JAR file with instrumentation classes to be defined by the bootstrap class loader. |
void |
appendToSystemClassLoaderSearch
(
JarFile
jarfile) Specifies a JAR file with instrumentation classes to be defined by the system class loader. |
Class [] |
getAllLoadedClasses
() Returns an array of all classes currently loaded by the JVM. |
Class [] |
getInitiatedClasses
(
ClassLoader
loader) Returns an array of all classes for which loader is an initiating loader. |
long |
getObjectSize
(
Object
objectToSize) Returns an implementation-specific approximation of the amount of storage consumed by the specified object. |
![]() |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
boolean |
isNativeMethodPrefixSupported
() Returns whether the current JVM configuration supports setting a native method prefix . |
boolean |
isRedefineClassesSupported
() Returns whether or not the current JVM configuration supports redefinition of classes. |
boolean |
isRetransformClassesSupported
() Returns whether or not the current JVM configuration supports retransformation of classes. |
void |
redefineClasses
(
ClassDefinition
... definitions) Redefine the supplied set of classes using the supplied class files. |
boolean |
removeTransformer
(
ClassFileTransformer
transformer) Unregisters the supplied transformer. |
void |
retransformClasses
(
Class
<?>... classes) Retransform the supplied set of classes. |
void |
setNativeMethodPrefix
(
ClassFileTransformer
transformer,
String
prefix) This method modifies the failure handling of native method resolution by allowing retry with a prefix applied to the name. |
Method Detail |
---|
void addTransformer(ClassFileTransformer transformer, boolean canRetransform)
This method is intended for use in instrumentation, as described in the class specification .
void addTransformer(ClassFileTransformer transformer)
Same as addTransformer(transformer, false).
boolean removeTransformer(ClassFileTransformer transformer)
boolean isRetransformClassesSupported()
void retransformClasses(Class<?>... classes) throwsUnmodifiableClassException
ClassNotFoundException,UnmodifiableClassException
This function facilitates the instrumentation of already loaded classes. When classes are initially loaded or when they are redefined , the initial class file bytes can be transformed with the ClassFileTransformer . This function reruns the transformation process (whether or not a transformation has previously occurred). This retransformation follows these steps:
The order of transformation is described in the ( transform method. This same order is used in the automatic reapplication of retransformation incapable transforms.
The initial class file bytes represent the bytes passed to ClassLoader.defineClass or 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 retransformation may change method bodies, the constant pool and attributes. The retransformation must not add, remove or rename fields or methods, change the signatures of methods, or change inheritance. These restrictions maybe be lifted in future versions. 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 class specification .
boolean isRedefineClassesSupported()
void redefineClasses(ClassDefinition... definitions) throws ClassNotFoundException, UnmodifiableClassException
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) 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 redefinition may change method bodies, the constant pool and attributes. The redefinition must not add, remove or rename fields or methods, change the signatures of methods, or change inheritance. These restrictions maybe be lifted in future versions. 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 class specification .
boolean
isModifiableClass
(
Class
<?> theClass)
For a class to be retransformed,
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,
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.
Class[] getAllLoadedClasses()
Class[] getInitiatedClasses(ClassLoader loader)
long getObjectSize(Object objectToSize)
void appendToBootstrapClassLoaderSearch(JarFilejarfile)
jarfile) throwsClassLoaderConfigurationError
When the virtual machine's built-in class loader, known as the "bootstrap class loader", unsuccessfully searches for a class, the entries in the 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 behaviour 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 JAR file must not contain an entry that corresponds to a class with the same name as a class that is already loaded, or in process of being loaded, by a class loader other than the bootstrap class loader. For example, if the JAR file contains the entry COM/foo/Quux.class then this method will not succeed if the class COM.foo.Quux is already loaded by some class loader that is not the bootstrap class loader. This restriction ensures the instrumentation classes provided by the agent are defined by the bootstrap class loader.
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.
void appendToSystemClassLoaderSearch(JarFilejarfile)
jarfile) throwsClassLoaderConfigurationError
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 behaviour that is difficult to diagnose (see
appendToBootstrapClassLoaderSearch
The JAR file must not contain an entry that corresponds to a class with the same name as a class that is already loaded, or in process of being loaded, by a class loader that is a descendent of the system class loader. For example, if the JAR file contains the entry COM/foo/Quux.class, and there is a class loader L which returns the system class loader as its parent class loader for delegation, then the method will not succeed if loader L has loaded (or is in the process of loading) COM.foo.Quux. In addition the Class-Path attribute must not be present in the main section of the JAR manifest (see
JAR file specification
.
). These restrictions ensure that the instrumentation classes provided by the agent are defined by the system class loader (or its ascendents if the instrumentation classes can be defined by an ascendent class loader).
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
appendToSystemClassLoaderSearch method synchronizes on the system class loader and invokes the appendToClassPathForInstrumentation method with the parameter set to the path
name of the JAR file
is
obtained by invoking the
getName()
method on the jarfile and this is provided as the parameter to the appendtoClassPathForInstrumentation method.
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 system property .
boolean isNativeMethodPrefixSupported()
void setNativeMethodPrefix(ClassFileTransformer transformer, String prefix)
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:
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:
method(wrapped_foo) -> nativeImplementation(foo)For automatic resolution, the JVM will attempt:
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:
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 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.