/*
* @(#)Instrumentation.java 1.7 04/06/08
*
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package java.lang.instrument;
import java.io.File;
import java.io.IOException;
/*
* Copyright 2003 Wily Technology, Inc.
*/
/**
* 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.
*
* <P>
* The only way to access an instance of the <code>Instrumentation</code>
* interface is for the JVM to be launched in a way that indicates
* the agent class - see
* {@linkplain java.lang.instrument the package specification}.
* The <code>Instrumentation</code> instance is passed
* to the <code>premain</code> method of the agent class.
* Once an agent acquires the <code>Instrumentation</code> instance,
* the agent may call methods on the instance at any time.
*
* @since JDK1.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. If multiple transformers are
* registered, they will be called in the order added. If a transformer throws
* during execution, the JVM will still call the other registered transformers in order.
* The same transformer may be added more than once.
* All transformers registered with <code>addTransformer</code>
* will always see the class files before any external JVMTI ClassFileLoadHook event listener does.
* <P>
* This method is intended for use in instrumentation, as described in the
* {@linkplain Instrumentation class specification}.
*
* @param transformer the transformer to register
* @throws java.lang.NullPointerException if passed a <code>null</code> transformer
*/
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 <code>null</code> transformer
*/
boolean
removeTransformer(ClassFileTransformer transformer);
/**
* 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.
* 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. Operates on
* a set in order to allow interlocked changes to more than one class at the same time
* (a redefinition of class A can require a redefinition of class B).
*
* <P>
* 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.
*
* <P>
* 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.
*
* <P>
* Instances of the redefined class are not affected.
*
* <P>
* Registered transformers will be called before the redefine operation is applied.
*
* <P>
* 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.
*
* <P>
* A zero-length <code>definitions</code> array is allowed, in this case, this
* method does nothing.
*
* <P>
* If this method throws an exception, no classes have been redefined.
* <P>
* 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
* @throws java.lang.ClassNotFoundException if a specified class cannot be found
* @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified
* @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow
* redefinition ({@link #isRedefineClassesSupported} is false) or the redefinition made 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 <code>null</code>.
*
* @see #isRedefineClassesSupported
* @see #addTransformer
* @see java.lang.instrument.ClassFileTransformer
*/
void
redefineClasses(ClassDefinition[] definitions)
throws ClassNotFoundException, UnmodifiableClassException;
/**
* Returns an array of all classes currently loaded by the JVM.
*
* @return an array containing all the classes loaded by the JVM, zero-length if there are none
*/
Class[]
getAllLoadedClasses();
/**
* Returns an array of all classes for which <code>loader</code> is an initiating loader.
* If the supplied loader is <code>null</code>, classes initiated by the bootstrap class
* loader are returned.
*
* @param loader the loader whose initiated class list will be returned
* @return an array containing all the classes for which loader is an initiating loader,
* zero-length if there are none
*/
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 <code>null</code>.
*/
long
getObjectSize(Object objectToSize);
}
|
