/*
 * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.lang.instrument;

import java.security.AccessController;
import java.security.PrivilegedAction;
import java.security.ProtectionDomain;

/*
 * Copyright 2003 Wily Technology, Inc.
 */

A transformer of class files. An agent registers an implementation of this interface using the addTransformer method so that the transformer's 
transform method is invoked when classes are loaded, redefined, or retransformed. The implementation should override one of the transform methods defined here. Transformers are invoked before the class is defined by the Java virtual machine. 

There are two kinds of transformers, determined by the canRetransform parameter of Instrumentation.addTransformer(ClassFileTransformer, boolean): 

   
retransformation capable transformers that were added with
       canRetransform as true
   
   
retransformation incapable transformers that were added with
       canRetransform as false or where added with Instrumentation.addTransformer(ClassFileTransformer) 
 
 Once a transformer has been registered with 
addTransformer, the transformer will be called for every new class definition and every class redefinition. Retransformation capable transformers will also be called on every class retransformation. The request for a new class definition is made with ClassLoader.defineClass or its native equivalents. The request for a class redefinition is made with Instrumentation.redefineClasses or its native equivalents. The request for a class retransformation is made with Instrumentation.retransformClasses or its native equivalents. The transformer is called during the processing of the request, before the class file bytes have been verified or applied. When there are multiple transformers, transformations are composed by chaining the transform calls.
That is, the byte array returned by one call to transform becomes the input
(via the classfileBuffer parameter) to the next call.

Transformations are applied in the following order:
 

   
Retransformation incapable transformers
   
   
Retransformation incapable native transformers
   
   
Retransformation capable transformers
   
   
Retransformation capable native transformers
   
 

For retransformations, the retransformation incapable transformers are not
called, instead the result of the previous transformation is reused.
In all other cases, this method is called.
Within each of these groupings, transformers are called in the order registered.
Native transformers are provided by the ClassFileLoadHook event
in the Java Virtual Machine Tool Interface).

The input (via the classfileBuffer parameter) to the first
transformer is:
 

   
for new class definition,
       the bytes passed to ClassLoader.defineClass
   
   
for class redefinition,
       definitions.getDefinitionClassFile() where
       definitions is the parameter to 
        Instrumentation.redefineClasses 
   
for class retransformation, the bytes passed to the new class definition or, if redefined, the last redefinition, with all transformations made by retransformation incapable transformers reapplied automatically and unaltered; for details see 
         Instrumentation.retransformClasses 
 

If the implementing method determines that no transformations are needed,
it should return null.
Otherwise, it should create a new byte[] array,
copy the input classfileBuffer into it,
along with all desired transformations, and return the new array.
The input classfileBuffer must not be modified.

In the retransform and redefine cases,
the transformer must support the redefinition semantics:
if a class that the transformer changed during initial definition is later
retransformed or redefined, the
transformer must insure that the second class output class file is a legal
redefinition of the first output class file.

If the transformer throws an exception (which it doesn't catch),
subsequent transformers will still be called and the load, redefine
or retransform will still be attempted.
Thus, throwing an exception has the same effect as returning null.
To prevent unexpected behavior when unchecked exceptions are generated
in transformer code, a transformer can catch Throwable.
If the transformer believes the classFileBuffer does not
represent a validly formatted class file, it should throw
an IllegalClassFormatException;
while this has the same effect as returning null. it facilitates the
logging or debugging of format corruptions.

Note the term class file is used as defined in section 3.1 of
The Java™ Virtual Machine Specification, to mean a
sequence of bytes in class file format, whether or not they reside in a
file.
See Also:
Instrumentation
Since:
  1.5/**
 * A transformer of class files. An agent registers an implementation of this
 * interface using the {@link Instrumentation#addTransformer addTransformer}
 * method so that the transformer's {@link
 * ClassFileTransformer#transform(Module,ClassLoader,String,Class,ProtectionDomain,byte[])
 * transform} method is invoked when classes are loaded,
 * {@link Instrumentation#redefineClasses redefined}, or
 * {@link Instrumentation#retransformClasses retransformed}. The implementation
 * should override one of the {@code transform} methods defined here.
 * Transformers are invoked before the class is defined by the Java virtual
 * machine.
 *
 * <P>
 * There are two kinds of transformers, determined by the <code>canRetransform</code>
 * parameter of
 * {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer,boolean)}:
 *  <ul>
 *    <li><i>retransformation capable</i> transformers that were added with
 *        <code>canRetransform</code> as true
 *    </li>
 *    <li><i>retransformation incapable</i> transformers that were added with
 *        <code>canRetransform</code> as false or where added with
 *        {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer)}
 *    </li>
 *  </ul>
 *
 * <P>
 * Once a transformer has been registered with
 * {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer,boolean)
 * addTransformer},
 * the transformer will be called for every new class definition and every class redefinition.
 * Retransformation capable transformers will also be called on every class retransformation.
 * The request for a new class definition is made with
 * {@link java.lang.ClassLoader#defineClass ClassLoader.defineClass}
 * or its native equivalents.
 * The request for a class redefinition is made with
 * {@link java.lang.instrument.Instrumentation#redefineClasses Instrumentation.redefineClasses}
 * or its native equivalents.
 * The request for a class retransformation is made with
 * {@link java.lang.instrument.Instrumentation#retransformClasses Instrumentation.retransformClasses}
 * or its native equivalents.
 * The transformer is called during the processing of the request, before the class file bytes
 * have been verified or applied.
 * When there are multiple transformers, transformations are composed by chaining the
 * <code>transform</code> calls.
 * That is, the byte array returned by one call to <code>transform</code> becomes the input
 * (via the <code>classfileBuffer</code> parameter) to the next call.
 *
 * <P>
 * Transformations are applied in the following order:
 *  <ul>
 *    <li>Retransformation incapable transformers
 *    </li>
 *    <li>Retransformation incapable native transformers
 *    </li>
 *    <li>Retransformation capable transformers
 *    </li>
 *    <li>Retransformation capable native transformers
 *    </li>
 *  </ul>
 *
 * <P>
 * For retransformations, the retransformation incapable transformers are not
 * called, instead the result of the previous transformation is reused.
 * In all other cases, this method is called.
 * Within each of these groupings, transformers are called in the order registered.
 * Native transformers are provided by the <code>ClassFileLoadHook</code> event
 * in the Java Virtual Machine Tool Interface).
 *
 * <P>
 * The input (via the <code>classfileBuffer</code> parameter) to the first
 * transformer is:
 *  <ul>
 *    <li>for new class definition,
 *        the bytes passed to <code>ClassLoader.defineClass</code>
 *    </li>
 *    <li>for class redefinition,
 *        <code>definitions.getDefinitionClassFile()</code> where
 *        <code>definitions</code> is the parameter to
 *        {@link java.lang.instrument.Instrumentation#redefineClasses
 *         Instrumentation.redefineClasses}
 *    </li>
 *    <li>for class retransformation,
 *         the bytes passed to the new class definition or, if redefined,
 *         the last redefinition, with all transformations made by retransformation
 *         incapable transformers reapplied automatically and unaltered;
 *         for details see
 *         {@link java.lang.instrument.Instrumentation#retransformClasses
 *          Instrumentation.retransformClasses}
 *    </li>
 *  </ul>
 *
 * <P>
 * If the implementing method determines that no transformations are needed,
 * it should return <code>null</code>.
 * Otherwise, it should create a new <code>byte[]</code> array,
 * copy the input <code>classfileBuffer</code> into it,
 * along with all desired transformations, and return the new array.
 * The input <code>classfileBuffer</code> must not be modified.
 *
 * <P>
 * In the retransform and redefine cases,
 * the transformer must support the redefinition semantics:
 * if a class that the transformer changed during initial definition is later
 * retransformed or redefined, the
 * transformer must insure that the second class output class file is a legal
 * redefinition of the first output class file.
 *
 * <P>
 * If the transformer throws an exception (which it doesn't catch),
 * subsequent transformers will still be called and the load, redefine
 * or retransform will still be attempted.
 * Thus, throwing an exception has the same effect as returning <code>null</code>.
 * To prevent unexpected behavior when unchecked exceptions are generated
 * in transformer code, a transformer can catch <code>Throwable</code>.
 * If the transformer believes the <code>classFileBuffer</code> does not
 * represent a validly formatted class file, it should throw
 * an <code>IllegalClassFormatException</code>;
 * while this has the same effect as returning null. it facilitates the
 * logging or debugging of format corruptions.
 *
 * <P>
 * Note the term <i>class file</i> is used as defined in section 3.1 of
 * <cite>The Java&trade; Virtual Machine Specification</cite>, to mean a
 * sequence of bytes in class file format, whether or not they reside in a
 * file.
 *
 * @see     java.lang.instrument.Instrumentation
 * @since   1.5
 */

public interface ClassFileTransformer {

    
Transforms the given class file and returns a new replacement class file. This method is invoked when the Module bearing 
transform is not overridden. 
Params:
loader –  the defining loader of the class to be transformed, may be null if the bootstrap loader
className –             the name of the class in the internal form of fully
                             qualified class and interface names as defined in
                             The Java Virtual Machine Specification.
                             For example, "java/util/List".
classBeingRedefined –  if this is triggered by a redefine or retransform, the class being redefined or retransformed; if this is a class load, null
protectionDomain –      the protection domain of the class being defined or redefined
classfileBuffer –       the input byte buffer in class file format - must not be modified
Throws:
IllegalClassFormatException – 
        if the input does not represent a well-formed class file
Implementation Requirements:
The default implementation returns null.
Returns:
a well-formed class file buffer (the result of the transform), or null if no transform is performed
@revised
9
@spec
JPMS/**
     * Transforms the given class file and returns a new replacement class file.
     * This method is invoked when the {@link Module Module} bearing {@link
     * ClassFileTransformer#transform(Module,ClassLoader,String,Class,ProtectionDomain,byte[])
     * transform} is not overridden.
     *
     * @implSpec The default implementation returns null.
     *
     * @param loader                the defining loader of the class to be transformed,
     *                              may be {@code null} if the bootstrap loader
     * @param className             the name of the class in the internal form of fully
     *                              qualified class and interface names as defined in
     *                              <i>The Java Virtual Machine Specification</i>.
     *                              For example, <code>"java/util/List"</code>.
     * @param classBeingRedefined   if this is triggered by a redefine or retransform,
     *                              the class being redefined or retransformed;
     *                              if this is a class load, {@code null}
     * @param protectionDomain      the protection domain of the class being defined or redefined
     * @param classfileBuffer       the input byte buffer in class file format - must not be modified
     *
     * @throws IllegalClassFormatException
     *         if the input does not represent a well-formed class file
     * @return a well-formed class file buffer (the result of the transform),
     *         or {@code null} if no transform is performed
     *
     * @revised 9
     * @spec JPMS
     */
    default byte[]
    transform(  ClassLoader         loader,
                String              className,
                Class<?>            classBeingRedefined,
                ProtectionDomain    protectionDomain,
                byte[]              classfileBuffer)
        throws IllegalClassFormatException {
        return null;
    }


    
Transforms the given class file and returns a new replacement class file.
Params:
module –                the module of the class to be transformed
loader –  the defining loader of the class to be transformed, may be null if the bootstrap loader
className –             the name of the class in the internal form of fully
                             qualified class and interface names as defined in
                             The Java Virtual Machine Specification.
                             For example, "java/util/List".
classBeingRedefined –  if this is triggered by a redefine or retransform, the class being redefined or retransformed; if this is a class load, null
protectionDomain –      the protection domain of the class being defined or redefined
classfileBuffer –       the input byte buffer in class file format - must not be modified
Throws:
IllegalClassFormatException – 
        if the input does not represent a well-formed class file
Implementation Requirements:
The default implementation of this method invokes the transform method.
Returns:
a well-formed class file buffer (the result of the transform), or null if no transform is performed
Since:
 9
@spec
JPMS/**
     * Transforms the given class file and returns a new replacement class file.
     *
     * @implSpec The default implementation of this method invokes the
     * {@link #transform(ClassLoader,String,Class,ProtectionDomain,byte[]) transform}
     * method.
     *
     * @param module                the module of the class to be transformed
     * @param loader                the defining loader of the class to be transformed,
     *                              may be {@code null} if the bootstrap loader
     * @param className             the name of the class in the internal form of fully
     *                              qualified class and interface names as defined in
     *                              <i>The Java Virtual Machine Specification</i>.
     *                              For example, <code>"java/util/List"</code>.
     * @param classBeingRedefined   if this is triggered by a redefine or retransform,
     *                              the class being redefined or retransformed;
     *                              if this is a class load, {@code null}
     * @param protectionDomain      the protection domain of the class being defined or redefined
     * @param classfileBuffer       the input byte buffer in class file format - must not be modified
     *
     * @throws IllegalClassFormatException
     *         if the input does not represent a well-formed class file
     * @return a well-formed class file buffer (the result of the transform),
     *         or {@code null} if no transform is performed
     *
     * @since  9
     * @spec JPMS
     */
    default byte[]
    transform(  Module              module,
                ClassLoader         loader,
                String              className,
                Class<?>            classBeingRedefined,
                ProtectionDomain    protectionDomain,
                byte[]              classfileBuffer)
        throws IllegalClassFormatException {

        // invoke the legacy transform method
        return transform(loader,
                         className,
                         classBeingRedefined,
                         protectionDomain,
                         classfileBuffer);
    }
}