| /* |
| * 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; |
| |
| import java.security.ProtectionDomain; |
| |
| /** |
| * This interface must be implemented by types used to instrument classes as |
| * they are loaded by a running VM. Implementations are registered by agents in |
| * the {@link java.lang.instrument.Instrumentation#addTransformer} operation. |
| * Once registered, a <code>ClassFileTransformer</code> has the opportunity to |
| * instrument every class that is loaded or redefined by the VM provided that |
| * the transformer does not have a dependency on that class. |
| * <p> |
| * Transformations of classes takes place just prior to them being defined by |
| * the VM. |
| * </p> |
| * |
| */ |
| public interface ClassFileTransformer { |
| |
| /** |
| * Receives a <code>byte</code> array containing the raw contents of a |
| * class for <i>possible</i> transformation into a new <code>byte</code> |
| * array which gets returned to the caller. It is left up to the |
| * implementation to decide what, if any, transformations are carried out |
| * and returned. |
| * <p> |
| * Requests for class transformations can occur in two situations. |
| * <ul> |
| * <li>the attempted defining of a class using |
| * {@link ClassLoader#defineClass(java.lang.String, byte[], int, int)} |
| * <li>the attempted re-defining of a previously defined class using |
| * {@link Instrumentation#redefineClasses(ClassDefinition[])} |
| * </ul> |
| * In both cases this operation will be called before the verification of |
| * the specified bytes in the <code>Class</code> file format. Each |
| * registered <code>ClassFileTransformer</code> instance will have this |
| * operation called on it. The order of the invocations matches the order in |
| * which the transformers were registered using the method |
| * {@link Instrumentation#addTransformer(ClassFileTransformer)}. |
| * </p> |
| * <p> |
| * Provided that the implementation of this method wishes to carry out a |
| * transformation, the return is a newly allocated <code>byte</code> array |
| * which contains <i>a copy of</i> the <code>classfileBuffer</code> |
| * argument plus the transformations to the array specific to the method |
| * implementation. If the transformer is written so as to pass on the |
| * opportunity to modify a given input then the return value should be |
| * <code>null</code>. |
| * </p> |
| * |
| * @param loader |
| * the <i>defining</i> <code>ClassLoader</code> for the |
| * candidate class to be transformed. |
| * @param className |
| * the fully qualified name of the candidate class to be |
| * transformed in the <i>fully/qualified/Name</i> format. |
| * @param classBeingRedefined |
| * if a class redefinition is in process then this argument will |
| * be the <code>Class</code> object for the class. Otherwise, |
| * if a class definition is in process, a <code>null</code>. |
| * @param protectionDomain |
| * the security protection domain for the class being defined or |
| * redefined. |
| * @param classfileBuffer |
| * a <code>byte</code> array containing the class to be |
| * transformed in <code>Class</code> file format. |
| * <em>This argument |
| * must not be modified</em>. |
| * @return if transformation occurs, a newly allocated <code>byte</code> |
| * array containing the modified version of |
| * <code>classfileBuffer</code>, otherwise <code>null</code>. |
| * @throws IllegalClassFormatException |
| * if the <code>classfileBuffer</code> does not contain a |
| * well-formed representation of a class in the |
| * <code>Class</code> file format. Note that if an invocation |
| * of this operation ends on an exception throw then (a) the |
| * remaining transformers in the "chain" will still |
| * have this method called, and (b) the class definition or |
| * redefinition that was the catalyst for the transformation |
| * opportunities will still be attempted. |
| */ |
| public byte[] transform(ClassLoader loader, String className, |
| Class<?> classBeingRedefined, ProtectionDomain protectionDomain, |
| byte[] classfileBuffer) throws IllegalClassFormatException; |
| } |