File Doc Category Size Date Package
ClassFileTransformer.java API Doc Android 1.5 API 5173 Wed May 06 22:41:02 BST 2009 java.lang.instrument

ClassFileTransformer

public interface ClassFileTransformer

This interface must be implemented by types used to instrument classes as they are loaded by a running VM. Implementations are registered by agents in the {@link java.lang.instrument.Instrumentation#addTransformer} operation. Once registered, a ClassFileTransformer has the opportunity to instrument every class that is loaded or redefined by the VM provided that the transformer does not have a dependency on that class.

Transformations of classes takes place just prior to them being defined by the VM.

Fields Summary
Constructors Summary
Methods Summary
public byte[] transform(java.lang.ClassLoader loader, java.lang.String className, java.lang.Class classBeingRedefined, java.security.ProtectionDomain protectionDomain, byte[] classfileBuffer)
Receives a byte array containing the raw contents of a class for possible transformation into a new byte array which gets returned to the caller. It is left up to the implementation to decide what, if any, transformations are carried out and returned.
Requests for class transformations can occur in two situations.

the attempted defining of a class using {@link ClassLoader#defineClass(java.lang.String, byte[], int, int)}
the attempted re-defining of a previously defined class using {@link Instrumentation#redefineClasses(ClassDefinition[])}
In both cases this operation will be called before the verification of the specified bytes in the Class file format. Each registered ClassFileTransformer instance will have this operation called on it. The order of the invocations matches the order in which the transformers were registered using the method {@link Instrumentation#addTransformer(ClassFileTransformer)}.

Provided that the implementation of this method wishes to carry out a transformation, the return is a newly allocated byte array which contains a copy of the classfileBuffer argument plus the transformations to the array specific to the method implementation. If the transformer is written so as to pass on the opportunity to modify a given input then the return value should be null.
param
loader the defining ClassLoader for the candidate class to be transformed.
param
className the fully qualified name of the candidate class to be transformed in the fully/qualified/Name format.
param
classBeingRedefined if a class redefinition is in process then this argument will be the Class object for the class. Otherwise, if a class definition is in process, a null.
param
protectionDomain the security protection domain for the class being defined or redefined.
param
classfileBuffer a byte array containing the class to be transformed in Class file format. This argument must not be modified.
return
if transformation occurs, a newly allocated byte array containing the modified version of classfileBuffer, otherwise null.
throws
IllegalClassFormatException if the classfileBuffer does not contain a well-formed representation of a class in the Class file format. Note that if an invocation of this operation ends on an exception throw then (a) the remaining transformers in the "chain" will still have this method called, and (b) the class definition or redefinition that was the catalyst for the transformation opportunities will still be attempted.