/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.lang.instrument;
/**
* Instances of this interface may be used by Java instrumentation agent code
* for support in carrying out the runtime instrumentation of classes. Using
* such an approach, classes may be enhanced with services such as profiling,
* logging or tracing which were not included in the source of the original
* class.
* <p>
* A concrete instance of this interface is made available as an input argument
* to all Java instrumentation agents'
* <code>premain(String agentArgs, Instrumentation inst)</code> method.
* </p>
*
*/
public interface Instrumentation {
/**
* Registers the supplied <code>transformer</code> argument with the VM.
* Any classes that are to be defined or re-defined (if supported) in the VM
* will then be offered to the transformer for it to carry out any byte code
* modifications. The exception to this scheme is if the class to be defined /
* re-defined is a dependency of the transformer.
* <p>
* This operation can be carried out multiple times on a concrete
* <code>Instrumentation</code>. The order of registration is important
* as it defines the order in which the transformers' transformation
* operation gets called.
* <p>
* <p>
* It is possible for any given instance of
* <code>ClassFileTransformer</code> to be registered more than once with
* this operation.
*
* @param transformer
* a class file transformer
* @throws NullPointerException
* if <code>transformer</code> is <code>null</code>.
*/
public void addTransformer(ClassFileTransformer transformer);
/**
* Returns an array of all of the classes that have been loaded into the VM.
*
* @return an array of <code>Class</code> objects with each element
* identifying a class that has been loaded into the VM.
*/
public Class[] getAllLoadedClasses();
/**
* Returns an array of all of the classes for which <code>loader</code> is
* the <i>initiating</i> class loader.
*
* @param loader
* a class loader. In order to obtain the array of classes
* initiated by the bootstrap class loader this argument should
* be <code>null</code>.
* @return an array of <code>Class</code> objects with each element
* identifying a class that has been initiated by the specified
* class loader.
*/
public Class[] getInitiatedClasses(ClassLoader loader);
/**
* Returns the number of bytes in memory required by this VM for the
* supplied object <code>objectToSize</code>. The returned value should
* be taken as an estimation only which is susceptible to change between
* separate launches of the VM.
*
* @param objectToSize
* any object
* @return an approximation of the number of bytes in memory taken up by
* <code>objectToSize</code>.
* @throws NullPointerException
* if the given object is null.
*/
public long getObjectSize(Object objectToSize);
/**
* Returns a boolean indication of whether or not this VM supports the
* on-the-fly redefining of classes that have been already loaded.
*
* @return <code>true</code> if class redefining is supported, otherwise
* <code>false</code>.
*/
public boolean isRedefineClassesSupported();
/**
* Receives an array of {@link ClassDefinition} instances and attempts to
* carry out on-the-fly redefining on each of the associated classes.
* Redefining in this manner may be used to update the following parts of an
* already loaded class:
* <ul>
* <li>attributes
* <li>constant pool
* <li>method implementations
* </ul>
* If any invocations of a redefined method are already active in the VM
* when this call is made then they will run to completion and be unaffected
* by the outcome of this method. Provided the method redefinition is
* successful, all subsequent calls on the method will run the new version.
* <br>
* Redefining a class may <em>not</em> be used to make changes to any
* other aspects of a previously loaded class such as its inheritance
* hierarchy, the names or signatures of any of its methods, the names of
* any fields, the values of any static variables etc.
* <p>
* If a class associated with a <code>ClassDefinition</code> is
* successfully redefined then there will be no resulting re-run of any of
* its initialization code. Similarly, any instances of the class that were
* created before the redefining will not be changed in any way. That is,
* they will remain in the VM as instances of the previous version of the
* class.
* </p>
* <p>
* Note that before the requested redefinitions are attempted, each
* {@link ClassFileTransformer} registered with the VM will be given the
* opportunity to carry out their own custom transformations of the new
* version of the class.
* </p>
*
* @param definitions
* an array of <code>ClassDefinition</code> objects wrapping
* the details of the classes to be redefined. A zero-length
* array value will not cause an error but, instead, will
* silently do nothing.
* @throws ClassNotFoundException
* if any of the classes specified in the contents of
* <code>definitions</code> cannot be located.
* @throws UnmodifiableClassException
* if any of the classes specified in the contents of
* <code>definitions</code> cannot be modified.
* @throws UnsupportedOperationException
* if this method is not supported in by the VM. May be checked
* in advance by calling {@link #isRedefineClassesSupported()}.
* @throws ClassFormatError
* if any of the <code>definitions</code> elements has been
* created with a <code>byte</code> array containing a badly
* formed class file.
* @throws NoClassDefFoundError
* if there is disagreement between the name of a class to be
* redefined and the name of the class from the corresponding
* class file format byte array.
* @throws UnsupportedClassVersionError
* if the version of any of the classes to be redefined is not
* supported by the VM.
* @throws ClassCircularityError
* if a circular dependency is detected among the classes to be
* redefined.
* @throws LinkageError
* if a linkage error situation is detected such that there is
* an incompatability between dependent classes.
* @throws NullPointerException
* if <code>definitions</code> or any of its elements are
* found to be <code>null</code>.
* @see #isRedefineClassesSupported()
*/
public void redefineClasses(ClassDefinition[] definitions)
throws ClassNotFoundException, UnmodifiableClassException;
/**
* Removes <i>the most recently added instance of</i> the
* <code>ClassFileTransformer</code> object from the VM's list of
* registered transformers. After this call completes, the specified
* <code>ClassFileTransformer</code> object will no longer have its
* <code>transform()<code> method automatically invoked when class definitions or
* redefinitions are attempted.
*
* @param transformer
* a previously registered <code>ClassFileTransformer</code>.
* @return <code>true</code> if <code>transformer</code> was located in
* the list of registered transformers and successfully removed.
* Otherwise, <code>false</code>.
* @throws NullPointerException
* if <code>transformer</code> is <code>null</code>.
*/
public boolean removeTransformer(ClassFileTransformer transformer);
}
|
