sample/java.lang.instrument.Instrumentation.txt

   1 *java.lang.instrument.Instrumentation* *Instrumentation* This class provides ser
   2
   3 public interface interface Instrumentation
   4
   5
   6 |java.lang.instrument.Instrumentation_Description|
   7 |java.lang.instrument.Instrumentation_Fields|
   8 |java.lang.instrument.Instrumentation_Constructors|
   9 |java.lang.instrument.Instrumentation_Methods|
  10
  11 ================================================================================
  12
  13 *java.lang.instrument.Instrumentation_Methods*
  14 |java.lang.instrument.Instrumentation.addTransformer(ClassFileTransformer)|Regi
  15 |java.lang.instrument.Instrumentation.getAllLoadedClasses()|Returns an array of
  16 |java.lang.instrument.Instrumentation.getInitiatedClasses(ClassLoader)|Returns
  17 |java.lang.instrument.Instrumentation.getObjectSize(Object)|Returns an implemen
  18 |java.lang.instrument.Instrumentation.isRedefineClassesSupported()|Returns whet
  19 |java.lang.instrument.Instrumentation.redefineClasses(ClassDefinition[])|Redefi
  20 |java.lang.instrument.Instrumentation.removeTransformer(ClassFileTransformer)|U
  21
  22 *java.lang.instrument.Instrumentation_Description*
  23
  24 This class provides services needed to instrument Java programming language
  25 code. Instrumentation is the addition of byte-codes to methods for the purpose
  26 of gathering data to be utilized by tools. Since the changes are purely
  27 additive, these tools do not modify application state or behavior. Examples of
  28 such benign tools include monitoring agents, profilers, coverage analyzers, and
  29 event loggers.
  30
  31 The only way to access an instance of the Instrumentation interface is for the
  32 JVM to be launched in a way that indicates the agent class - see the package
  33 specification(|java.lang.instrument|) . The Instrumentation instance is passed
  34 to the premain method of the agent class. Once an agent acquires the
  35 Instrumentation instance, the agent may call methods on the instance at any
  36 time.
  37
  38
  39 *java.lang.instrument.Instrumentation.addTransformer(ClassFileTransformer)*
  40
  41 public void addTransformer(java.lang.instrument.ClassFileTransformer transformer)
  42
  43 Registers the supplied transformer. All future class definitions will be seen
  44 by the transformer, except definitions of classes upon which any registered
  45 transformer is dependent. If multiple transformers are registered, they will be
  46 called in the order added. If a transformer throws during execution, the JVM
  47 will still call the other registered transformers in order. The same
  48 transformer may be added more than once. All transformers registered with
  49 addTransformer will always see the class files before any external JVMTI
  50 ClassFileLoadHook event listener does.
  51
  52 This method is intended for use in instrumentation, as described in the class
  53 specification(|java.lang.instrument.Instrumentation|) .
  54
  55     transformer - the transformer to register
  56
  57 *java.lang.instrument.Instrumentation.getAllLoadedClasses()*
  58
  59 public |java.lang.Class| getAllLoadedClasses()
  60
  61 Returns an array of all classes currently loaded by the JVM.
  62
  63
  64     Returns: an array containing all the classes loaded by the JVM, zero-length if there are
  65              none
  66 *java.lang.instrument.Instrumentation.getInitiatedClasses(ClassLoader)*
  67
  68 public |java.lang.Class| getInitiatedClasses(java.lang.ClassLoader loader)
  69
  70 Returns an array of all classes for which loader is an initiating loader. If
  71 the supplied loader is null, classes initiated by the bootstrap class loader
  72 are returned.
  73
  74     loader - the loader whose initiated class list will be returned
  75
  76     Returns: an array containing all the classes for which loader is an initiating loader,
  77              zero-length if there are none
  78 *java.lang.instrument.Instrumentation.getObjectSize(Object)*
  79
  80 public long getObjectSize(java.lang.Object objectToSize)
  81
  82 Returns an implementation-specific approximation of the amount of storage
  83 consumed by the specified object. The result may include some or all of the
  84 object's overhead, and thus is useful for comparison within an implementation
  85 but not between implementations.
  86
  87 The estimate may change during a single invocation of the JVM.
  88
  89     objectToSize - the object to size
  90
  91     Returns: an implementation-specific approximation of the amount of storage consumed by
  92              the specified object
  93 *java.lang.instrument.Instrumentation.isRedefineClassesSupported()*
  94
  95 public boolean isRedefineClassesSupported()
  96
  97 Returns whether or not the current JVM configuration supports redefinition of
  98 classes. The ability to redefine an already loaded class is an optional
  99 capability of a JVM. During a single instantiation of a single JVM, multiple
 100 calls to this method will always return the same answer.
 101
 102
 103     Returns: true if the current JVM configuration supports redefinition of classes, false
 104              if not.
 105 *java.lang.instrument.Instrumentation.redefineClasses(ClassDefinition[])*
 106
 107 public void redefineClasses(java.lang.instrument.ClassDefinition[] definitions)
 108   throws |java.lang.ClassNotFoundException|
 109          |java.lang.instrument.UnmodifiableClassException|
 110
 111 Redefine the supplied set of classes using the supplied class files. Operates
 112 on a set in order to allow interlocked changes to more than one class at the
 113 same time (a redefinition of class A can require a redefinition of class B).
 114
 115 If a redefined method has active stack frames, those active frames continue to
 116 run the bytecodes of the original method. The redefined method will be used on
 117 new invokes.
 118
 119 This method does not cause any initialization except that which would occur
 120 under the customary JVM semantics. In other words, redefining a class does not
 121 cause its initializers to be run. The values of static variables will remain as
 122 they were prior to the call.
 123
 124 Instances of the redefined class are not affected.
 125
 126 Registered transformers will be called before the redefine operation is
 127 applied.
 128
 129 The redefinition may change method bodies, the constant pool and attributes.
 130 The redefinition must not add, remove or rename fields or methods, change the
 131 signatures of methods, or change inheritance. These restrictions maybe be
 132 lifted in future versions.
 133
 134 A zero-length definitions array is allowed, in this case, this method does
 135 nothing.
 136
 137 If this method throws an exception, no classes have been redefined.
 138
 139 This method is intended for use in instrumentation, as described in the class
 140 specification(|java.lang.instrument.Instrumentation|) .
 141
 142     definitions - array of classes to redefine with corresponding definitions
 143
 144 *java.lang.instrument.Instrumentation.removeTransformer(ClassFileTransformer)*
 145
 146 public boolean removeTransformer(java.lang.instrument.ClassFileTransformer transformer)
 147
 148 Unregisters the supplied transformer. Future class definitions will not be
 149 shown to the transformer. Removes the most-recently-added matching instance of
 150 the transformer. Due to the multi-threaded nature of class loading, it is
 151 possible for a transformer to receive calls after it has been removed.
 152 Transformers should be written defensively to expect this situation.
 153
 154     transformer - the transformer to unregister
 155
 156     Returns: true if the transformer was found and removed, false if the transformer was not
 157              found
 158