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: import java.security.ProtectionDomain;
021:
022: /**
023: * This interface must be implemented by types used to instrument classes as
024: * they are loaded by a running VM. Implementations are registered by agents in
025: * the {@link java.lang.instrument.Instrumentation#addTransformer} operation.
026: * Once registered, a <code>ClassFileTransformer</code> has the opportunity to
027: * instrument every class that is loaded or redefined by the VM provided that
028: * the transformer does not have a dependency on that class.
029: * <p>
030: * Transformations of classes takes place just prior to them being defined by
031: * the VM.
032: * </p>
033: *
034: */
035: public interface ClassFileTransformer {
036:
037: /**
038: * Receives a <code>byte</code> array containing the raw contents of a
039: * class for <i>possible</i> transformation into a new <code>byte</code>
040: * array which gets returned to the caller. It is left up to the
041: * implementation to decide what, if any, transformations are carried out
042: * and returned.
043: * <p>
044: * Requests for class transformations can occur in two situations.
045: * <ul>
046: * <li>the attempted defining of a class using
047: * {@link ClassLoader#defineClass(java.lang.String, byte[], int, int)}
048: * <li>the attempted re-defining of a previously defined class using
049: * {@link Instrumentation#redefineClasses(ClassDefinition[])}
050: * </ul>
051: * In both cases this operation will be called before the verification of
052: * the specified bytes in the <code>Class</code> file format. Each
053: * registered <code>ClassFileTransformer</code> instance will have this
054: * operation called on it. The order of the invocations matches the order in
055: * which the transformers were registered using the method
056: * {@link Instrumentation#addTransformer(ClassFileTransformer)}.
057: * </p>
058: * <p>
059: * Provided that the implementation of this method wishes to carry out a
060: * transformation, the return is a newly allocated <code>byte</code> array
061: * which contains <i>a copy of</i> the <code>classfileBuffer</code>
062: * argument plus the transformations to the array specific to the method
063: * implementation. If the transformer is written so as to pass on the
064: * opportunity to modify a given input then the return value should be
065: * <code>null</code>.
066: * </p>
067: *
068: * @param loader
069: * the <i>defining</i> <code>ClassLoader</code> for the
070: * candidate class to be transformed.
071: * @param className
072: * the fully qualified name of the candidate class to be
073: * transformed in the <i>fully/qualified/Name</i> format.
074: * @param classBeingRedefined
075: * if a class redefinition is in process then this argument will
076: * be the <code>Class</code> object for the class. Otherwise,
077: * if a class definition is in process, a <code>null</code>.
078: * @param protectionDomain
079: * the security protection domain for the class being defined or
080: * redefined.
081: * @param classfileBuffer
082: * a <code>byte</code> array containing the class to be
083: * transformed in <code>Class</code> file format.
084: * <em>This argument
085: * must not be modified</em>.
086: * @return if transformation occurs, a newly allocated <code>byte</code>
087: * array containing the modified version of
088: * <code>classfileBuffer</code>, otherwise <code>null</code>.
089: * @throws IllegalClassFormatException
090: * if the <code>classfileBuffer</code> does not contain a
091: * well-formed representation of a class in the
092: * <code>Class</code> file format. Note that if an invocation
093: * of this operation ends on an exception throw then (a) the
094: * remaining transformers in the "chain" will still
095: * have this method called, and (b) the class definition or
096: * redefinition that was the catalyst for the transformation
097: * opportunities will still be attempted.
098: */
099: public byte[] transform(ClassLoader loader, String className,
100: Class<?> classBeingRedefined,
101: ProtectionDomain protectionDomain, byte[] classfileBuffer)
102: throws IllegalClassFormatException;
103: }
|