001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.lang.instrument;
019:
020: /**
021: * Instances of this interface may be used by Java instrumentation agent code
022: * for support in carrying out the runtime instrumentation of classes. Using
023: * such an approach, classes may be enhanced with services such as profiling,
024: * logging or tracing which were not included in the source of the original
025: * class.
026: * <p>
027: * A concrete instance of this interface is made available as an input argument
028: * to all Java instrumentation agents'
029: * <code>premain(String agentArgs, Instrumentation inst)</code> method.
030: * </p>
031: *
032: */
033: public interface Instrumentation {
034:
035: /**
036: * Registers the supplied <code>transformer</code> argument with the VM.
037: * Any classes that are to be defined or re-defined (if supported) in the VM
038: * will then be offered to the transformer for it to carry out any byte code
039: * modifications. The exception to this scheme is if the class to be defined /
040: * re-defined is a dependency of the transformer.
041: * <p>
042: * This operation can be carried out multiple times on a concrete
043: * <code>Instrumentation</code>. The order of registration is important
044: * as it defines the order in which the transformers' transformation
045: * operation gets called.
046: * <p>
047: * <p>
048: * It is possible for any given instance of
049: * <code>ClassFileTransformer</code> to be registered more than once with
050: * this operation.
051: *
052: * @param transformer
053: * a class file transformer
054: * @throws NullPointerException
055: * if <code>transformer</code> is <code>null</code>.
056: */
057: public void addTransformer(ClassFileTransformer transformer);
058:
059: /**
060: * Returns an array of all of the classes that have been loaded into the VM.
061: *
062: * @return an array of <code>Class</code> objects with each element
063: * identifying a class that has been loaded into the VM.
064: */
065: public Class[] getAllLoadedClasses();
066:
067: /**
068: * Returns an array of all of the classes for which <code>loader</code> is
069: * the <i>initiating</i> class loader.
070: *
071: * @param loader
072: * a class loader. In order to obtain the array of classes
073: * initiated by the bootstrap class loader this argument should
074: * be <code>null</code>.
075: * @return an array of <code>Class</code> objects with each element
076: * identifying a class that has been initiated by the specified
077: * class loader.
078: */
079: public Class[] getInitiatedClasses(ClassLoader loader);
080:
081: /**
082: * Returns the number of bytes in memory required by this VM for the
083: * supplied object <code>objectToSize</code>. The returned value should
084: * be taken as an estimation only which is susceptible to change between
085: * separate launches of the VM.
086: *
087: * @param objectToSize
088: * any object
089: * @return an approximation of the number of bytes in memory taken up by
090: * <code>objectToSize</code>.
091: * @throws NullPointerException
092: * if the given object is null.
093: */
094: public long getObjectSize(Object objectToSize);
095:
096: /**
097: * Returns a boolean indication of whether or not this VM supports the
098: * on-the-fly redefining of classes that have been already loaded.
099: *
100: * @return <code>true</code> if class redefining is supported, otherwise
101: * <code>false</code>.
102: */
103: public boolean isRedefineClassesSupported();
104:
105: /**
106: * Receives an array of {@link ClassDefinition} instances and attempts to
107: * carry out on-the-fly redefining on each of the associated classes.
108: * Redefining in this manner may be used to update the following parts of an
109: * already loaded class:
110: * <ul>
111: * <li>attributes
112: * <li>constant pool
113: * <li>method implementations
114: * </ul>
115: * If any invocations of a redefined method are already active in the VM
116: * when this call is made then they will run to completion and be unaffected
117: * by the outcome of this method. Provided the method redefinition is
118: * successful, all subsequent calls on the method will run the new version.
119: * <br>
120: * Redefining a class may <em>not</em> be used to make changes to any
121: * other aspects of a previously loaded class such as its inheritance
122: * hierarchy, the names or signatures of any of its methods, the names of
123: * any fields, the values of any static variables etc.
124: * <p>
125: * If a class associated with a <code>ClassDefinition</code> is
126: * successfully redefined then there will be no resulting re-run of any of
127: * its initialization code. Similarly, any instances of the class that were
128: * created before the redefining will not be changed in any way. That is,
129: * they will remain in the VM as instances of the previous version of the
130: * class.
131: * </p>
132: * <p>
133: * Note that before the requested redefinitions are attempted, each
134: * {@link ClassFileTransformer} registered with the VM will be given the
135: * opportunity to carry out their own custom transformations of the new
136: * version of the class.
137: * </p>
138: *
139: * @param definitions
140: * an array of <code>ClassDefinition</code> objects wrapping
141: * the details of the classes to be redefined. A zero-length
142: * array value will not cause an error but, instead, will
143: * silently do nothing.
144: * @throws ClassNotFoundException
145: * if any of the classes specified in the contents of
146: * <code>definitions</code> cannot be located.
147: * @throws UnmodifiableClassException
148: * if any of the classes specified in the contents of
149: * <code>definitions</code> cannot be modified.
150: * @throws UnsupportedOperationException
151: * if this method is not supported in by the VM. May be checked
152: * in advance by calling {@link #isRedefineClassesSupported()}.
153: * @throws ClassFormatError
154: * if any of the <code>definitions</code> elements has been
155: * created with a <code>byte</code> array containing a badly
156: * formed class file.
157: * @throws NoClassDefFoundError
158: * if there is disagreement between the name of a class to be
159: * redefined and the name of the class from the corresponding
160: * class file format byte array.
161: * @throws UnsupportedClassVersionError
162: * if the version of any of the classes to be redefined is not
163: * supported by the VM.
164: * @throws ClassCircularityError
165: * if a circular dependency is detected among the classes to be
166: * redefined.
167: * @throws LinkageError
168: * if a linkage error situation is detected such that there is
169: * an incompatability between dependent classes.
170: * @throws NullPointerException
171: * if <code>definitions</code> or any of its elements are
172: * found to be <code>null</code>.
173: * @see #isRedefineClassesSupported()
174: */
175: public void redefineClasses(ClassDefinition[] definitions)
176: throws ClassNotFoundException, UnmodifiableClassException;
177:
178: /**
179: * Removes <i>the most recently added instance of</i> the
180: * <code>ClassFileTransformer</code> object from the VM's list of
181: * registered transformers. After this call completes, the specified
182: * <code>ClassFileTransformer</code> object will no longer have its
183: * <code>transform()<code> method automatically invoked when class definitions or
184: * redefinitions are attempted.
185: *
186: * @param transformer
187: * a previously registered <code>ClassFileTransformer</code>.
188: * @return <code>true</code> if <code>transformer</code> was located in
189: * the list of registered transformers and successfully removed.
190: * Otherwise, <code>false</code>.
191: * @throws NullPointerException
192: * if <code>transformer</code> is <code>null</code>.
193: */
194: public boolean removeTransformer(ClassFileTransformer transformer);
195: }
|