Instrumentation


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