< prev index next >

src/java.instrument/share/classes/java/lang/instrument/Instrumentation.java

Print this page




  48  * <P>
  49  * There are two ways to obtain an instance of the
  50  * <code>Instrumentation</code> interface:
  51  *
  52  * <ol>
  53  *   <li><p> When a JVM is launched in a way that indicates an agent
  54  *     class. In that case an <code>Instrumentation</code> instance
  55  *     is passed to the <code>premain</code> method of the agent class.
  56  *     </p></li>
  57  *   <li><p> When a JVM provides a mechanism to start agents sometime
  58  *     after the JVM is launched. In that case an <code>Instrumentation</code>
  59  *     instance is passed to the <code>agentmain</code> method of the
  60  *     agent code. </p> </li>
  61  * </ol>
  62  * <p>
  63  * These mechanisms are described in the
  64  * {@linkplain java.lang.instrument package specification}.
  65  * <p>
  66  * Once an agent acquires an <code>Instrumentation</code> instance,
  67  * the agent may call methods on the instance at any time.
  68  *
  69  * @apiNote This interface is not intended to be implemented outside of
  70  * the java.instrument module.
  71  *
  72  * @since   1.5
  73  */
  74 public interface Instrumentation {
  75     /**
  76      * Registers the supplied transformer. All future class definitions
  77      * will be seen by the transformer, except definitions of classes upon which any
  78      * registered transformer is dependent.
  79      * The transformer is called when classes are loaded, when they are
  80      * {@linkplain #redefineClasses redefined}. and if <code>canRetransform</code> is true,
  81      * when they are {@linkplain #retransformClasses retransformed}.
  82      * {@link ClassFileTransformer} defines the order of transform calls.
  83      *
  84      * If a transformer throws
  85      * an exception during execution, the JVM will still call the other registered
  86      * transformers in order. The same transformer may be added more than once,
  87      * but it is strongly discouraged -- avoid this by creating a new instance of
  88      * transformer class.




  48  * <P>
  49  * There are two ways to obtain an instance of the
  50  * <code>Instrumentation</code> interface:
  51  *
  52  * <ol>
  53  *   <li><p> When a JVM is launched in a way that indicates an agent
  54  *     class. In that case an <code>Instrumentation</code> instance
  55  *     is passed to the <code>premain</code> method of the agent class.
  56  *     </p></li>
  57  *   <li><p> When a JVM provides a mechanism to start agents sometime
  58  *     after the JVM is launched. In that case an <code>Instrumentation</code>
  59  *     instance is passed to the <code>agentmain</code> method of the
  60  *     agent code. </p> </li>
  61  * </ol>
  62  * <p>
  63  * These mechanisms are described in the
  64  * {@linkplain java.lang.instrument package specification}.
  65  * <p>
  66  * Once an agent acquires an <code>Instrumentation</code> instance,
  67  * the agent may call methods on the instance at any time.
  68  * <p>
  69  * @apiNote This interface is not intended to be implemented outside of
  70  * the java.instrument module.
  71  *
  72  * @since   1.5
  73  */
  74 public interface Instrumentation {
  75     /**
  76      * Registers the supplied transformer. All future class definitions
  77      * will be seen by the transformer, except definitions of classes upon which any
  78      * registered transformer is dependent.
  79      * The transformer is called when classes are loaded, when they are
  80      * {@linkplain #redefineClasses redefined}. and if <code>canRetransform</code> is true,
  81      * when they are {@linkplain #retransformClasses retransformed}.
  82      * {@link ClassFileTransformer} defines the order of transform calls.
  83      *
  84      * If a transformer throws
  85      * an exception during execution, the JVM will still call the other registered
  86      * transformers in order. The same transformer may be added more than once,
  87      * but it is strongly discouraged -- avoid this by creating a new instance of
  88      * transformer class.


< prev index next >