raphw / byte-buddy / #801

/*

 * Copyright 2014 - Present Rafael Winterhalter

 *

 * Licensed 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 net.bytebuddy.dynamic;

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;

import net.bytebuddy.ClassFileVersion;

import net.bytebuddy.asm.AsmVisitorWrapper;

import net.bytebuddy.build.HashCodeAndEqualsPlugin;

import net.bytebuddy.description.annotation.AnnotationDescription;

import net.bytebuddy.description.annotation.AnnotationList;

import net.bytebuddy.description.annotation.AnnotationValue;

import net.bytebuddy.description.field.FieldDescription;

import net.bytebuddy.description.method.MethodDescription;

import net.bytebuddy.description.method.ParameterDescription;

import net.bytebuddy.description.method.ParameterList;

import net.bytebuddy.description.modifier.FieldManifestation;

import net.bytebuddy.description.modifier.MethodManifestation;

import net.bytebuddy.description.modifier.ModifierContributor;

import net.bytebuddy.description.modifier.Ownership;

import net.bytebuddy.description.modifier.Visibility;

import net.bytebuddy.description.type.RecordComponentDescription;

import net.bytebuddy.description.type.TypeDefinition;

import net.bytebuddy.description.type.TypeDescription;

import net.bytebuddy.description.type.TypeList;

import net.bytebuddy.description.type.TypeVariableToken;

import net.bytebuddy.dynamic.loading.ClassLoadingStrategy;

import net.bytebuddy.dynamic.loading.InjectionClassLoader;

import net.bytebuddy.dynamic.scaffold.FieldRegistry;

import net.bytebuddy.dynamic.scaffold.InstrumentedType;

import net.bytebuddy.dynamic.scaffold.MethodGraph;

import net.bytebuddy.dynamic.scaffold.MethodRegistry;

import net.bytebuddy.dynamic.scaffold.RecordComponentRegistry;

import net.bytebuddy.dynamic.scaffold.TypeValidation;

import net.bytebuddy.dynamic.scaffold.TypeWriter;

import net.bytebuddy.implementation.EqualsMethod;

import net.bytebuddy.implementation.FieldAccessor;

import net.bytebuddy.implementation.HashCodeMethod;

import net.bytebuddy.implementation.Implementation;

import net.bytebuddy.implementation.LoadedTypeInitializer;

import net.bytebuddy.implementation.ToStringMethod;

import net.bytebuddy.implementation.attribute.AnnotationRetention;

import net.bytebuddy.implementation.attribute.AnnotationValueFilter;

import net.bytebuddy.implementation.attribute.FieldAttributeAppender;

import net.bytebuddy.implementation.attribute.MethodAttributeAppender;

import net.bytebuddy.implementation.attribute.RecordComponentAttributeAppender;

import net.bytebuddy.implementation.attribute.TypeAttributeAppender;

import net.bytebuddy.implementation.auxiliary.AuxiliaryType;

import net.bytebuddy.implementation.bytecode.ByteCodeAppender;

import net.bytebuddy.matcher.ElementMatcher;

import net.bytebuddy.matcher.LatentMatcher;

import net.bytebuddy.pool.TypePool;

import net.bytebuddy.utility.AsmClassReader;

import net.bytebuddy.utility.AsmClassWriter;

import net.bytebuddy.utility.CompoundList;

import net.bytebuddy.utility.FileSystem;

import net.bytebuddy.utility.nullability.MaybeNull;

import net.bytebuddy.utility.visitor.ContextClassVisitor;

import org.objectweb.asm.ClassVisitor;

import org.objectweb.asm.Opcodes;

import java.io.File;

import java.io.FileInputStream;

import java.io.FileOutputStream;

import java.io.IOException;

import java.io.InputStream;

import java.io.OutputStream;

import java.lang.annotation.Annotation;

import java.lang.reflect.AnnotatedElement;

import java.lang.reflect.Constructor;

import java.lang.reflect.Field;

import java.lang.reflect.Method;

import java.lang.reflect.Type;

import java.util.ArrayList;

import java.util.Arrays;

import java.util.Collection;

import java.util.Collections;

import java.util.HashMap;

import java.util.LinkedHashMap;

import java.util.LinkedHashSet;

import java.util.List;

import java.util.Map;

import java.util.Set;

import java.util.jar.Attributes;

import java.util.jar.JarEntry;

import java.util.jar.JarInputStream;

import java.util.jar.JarOutputStream;

import java.util.jar.Manifest;

import static net.bytebuddy.matcher.ElementMatchers.isConstructor;

import static net.bytebuddy.matcher.ElementMatchers.isDeclaredBy;

import static net.bytebuddy.matcher.ElementMatchers.isEquals;

import static net.bytebuddy.matcher.ElementMatchers.isHashCode;

import static net.bytebuddy.matcher.ElementMatchers.isInterface;

import static net.bytebuddy.matcher.ElementMatchers.isMethod;

import static net.bytebuddy.matcher.ElementMatchers.isSuperTypeOf;

import static net.bytebuddy.matcher.ElementMatchers.isSynthetic;

import static net.bytebuddy.matcher.ElementMatchers.isToString;

import static net.bytebuddy.matcher.ElementMatchers.none;

/**

 * A dynamic type that is created at runtime, usually as the result of applying a

 * {@link net.bytebuddy.dynamic.DynamicType.Builder} or as the result of an

 * {@link net.bytebuddy.implementation.auxiliary.AuxiliaryType}.

 * <p>&nbsp;</p>

 * Note that the {@link TypeDescription}s will represent their

 * unloaded forms and therefore differ from the loaded types, especially with regards to annotations.

 */

public interface DynamicType extends ClassFileLocator {

    /**

     * <p>

     * Returns a description of this dynamic type.

     * </p>

     * <p>

     * <b>Note</b>: This description will most likely differ from the binary representation of this type. Normally,

     * annotations and intercepted methods are not added to this type description.

     * </p>

     *

     * @return A description of this dynamic type.

     */

    TypeDescription getTypeDescription();

    /**

     * Returns a byte array representing this dynamic type. This byte array might be reused by this dynamic type and

     * must therefore not be altered.

     *

     * @return A byte array of the type's binary representation.

     */

    byte[] getBytes();

    /**

     * Returns the loaded type initializer of this dynamic type.

     *

     * @return The loaded type initializer of this dynamic type.

     */

    LoadedTypeInitializer getLoadedTypeInitializer();

    /**

     * Returns all auxiliary types of this dynamic type.

     *

     * @return A list of all auxiliary types of this dynamic type.

     */

    List<? extends DynamicType> getAuxiliaries();

    /**

     * Returns a set of all auxiliary types that are represented by this dynamic type.

     *

     * @return A set of all auxiliary types.

     */

    Set<TypeDescription> getAuxiliaryTypeDescriptions();

    /**

     * Returns a set of all types that are represented by this dynamic type.

     *

     * @return A set of all represented types.

     */

    Set<TypeDescription> getAllTypeDescriptions();

    /**

     * <p>

     * Returns a map of all auxiliary types that are required for making use of the main type.

     * </p>

     * <p>

     * <b>Note</b>: The type descriptions will most likely differ from the binary representation of this type.

     * Normally, annotations and intercepted methods are not added to the type descriptions of auxiliary types.

     * </p>

     *

     * @return A map of all auxiliary types by their descriptions to their binary representation.

     */

    Map<TypeDescription, byte[]> getAuxiliaryTypes();

    /**

     * Returns all types that are implied by this dynamic type.

     *

     * @return A mapping from all type descriptions, the actual type and its auxiliary types to their binary

     * representation

     */

    Map<TypeDescription, byte[]> getAllTypes();

    /**

     * <p>

     * Returns a map of all loaded type initializers for the main type and all auxiliary types, if any.

     * </p>

     * <p>

     * <b>Note</b>: The type descriptions will most likely differ from the binary representation of this type.

     * Normally, annotations and intercepted methods are not added to the type descriptions of auxiliary types.

     * </p>

     *

     * @return A mapping of all types' descriptions to their loaded type initializers.

     */

    Map<TypeDescription, LoadedTypeInitializer> getLoadedTypeInitializers();

    /**

     * Checks if a dynamic type requires some form of explicit type initialization, either for itself or for one

     * of its auxiliary types, if any. This is the case when this dynamic type was defined to delegate method calls

     * to a specific instance which is stored in a field of the created type. If this class serialized, it could not

     * be used without its loaded type initializers since the field value represents a specific runtime context.

     *

     * @return {@code true} if this type requires explicit type initialization.

     */

    boolean hasAliveLoadedTypeInitializers();

    /**

     * <p>

     * Saves a dynamic type in a given folder using the Java class file format while respecting the naming conventions

     * for saving compiled Java classes. All auxiliary types, if any, are saved in the same directory. The resulting

     * folder structure will resemble the structure that is required for Java run times, i.e. each folder representing

     * a segment of the package name. If the specified {@code folder} does not yet exist, it is created during the

     * call of this method.

     * </p>

     * <p>

     * <b>Note</b>: The type descriptions will most likely differ from the binary representation of this type.

     * Normally, annotations and intercepted methods are not added to the type descriptions of auxiliary types.

     * </p>

     *

     * @param folder The base target folder for storing this dynamic type and its auxiliary types, if any.

     * @return A map of type descriptions pointing to files with their stored binary representations within {@code folder}.

     * @throws IOException Thrown if the underlying file operations cause an {@code IOException}.

     */

    Map<TypeDescription, File> saveIn(File folder) throws IOException;

    /**

     * Injects the types of this dynamic type into a given <i>jar</i> file. Any pre-existent type with the same name

     * is overridden during injection. The resulting jar is going to be a recreation of the original jar and not a

     * patched version with a new central directory. No directory entries are added to the generated jar.

     *

     * @param sourceJar The original jar file.

     * @param targetJar The {@code source} jar file with the injected contents.

     * @return The {@code target} jar file.

     * @throws IOException If an I/O exception occurs while injecting from the source into the target.

     */

    File inject(File sourceJar, File targetJar) throws IOException;

    /**

     * Injects the types of this dynamic type into a given <i>jar</i> file. Any pre-existent type with the same name

     * is overridden during injection. The resulting jar is going to be a recreation of the original jar and not a

     * patched version with a new central directory. No directory entries are added to the generated jar.

     *

     * @param jar The jar file to replace with an injected version.

     * @return The {@code jar} file.

     * @throws IOException If an I/O exception occurs while injecting into the jar.

     */

    File inject(File jar) throws IOException;

    /**

     * Saves the contents of this dynamic type inside a <i>jar</i> file. The folder of the given {@code file} must

     * exist prior to calling this method. The jar file is created with a simple manifest that only contains a version

     * number. No directory entries are added to the generated jar.

     *

     * @param file The target file to which the <i>jar</i> is written to.

     * @return The given {@code file}.

     * @throws IOException If an I/O exception occurs while writing the file.

     */

    File toJar(File file) throws IOException;

    /**

     * Saves the contents of this dynamic type inside a <i>jar</i> file. The folder of the given {@code file} must

     * exist prior to calling this method. No directory entries are added to the generated jar.

     *

     * @param file     The target file to which the <i>jar</i> is written to.

     * @param manifest The manifest of the created <i>jar</i>.

     * @return The given {@code file}.

     * @throws IOException If an I/O exception occurs while writing the file.

     */

    File toJar(File file, Manifest manifest) throws IOException;

    /**

     * {@inheritDoc}

     */

    void close();

    /**

     * A builder for creating a dynamic type.

     *

     * @param <T> A loaded type that the built type is guaranteed to be a subclass of.

     */

    interface Builder<T> {

        /**

         * Applies the supplied {@link AsmVisitorWrapper} onto the {@link org.objectweb.asm.ClassVisitor} during building a dynamic type.

         * Using an ASM visitor, it is possible to manipulate byte code directly. Byte Buddy does not validate directly created byte code

         * and it remains the responsibility of the visitor's implementor to generate legal byte code. If several ASM visitor wrappers

         * are registered, they are applied on top of another in their registration order.

         *

         * @param asmVisitorWrapper The ASM visitor wrapper to apply during

         * @return A new builder that is equal to this builder and applies the ASM visitor wrapper.

         */

        Builder<T> visit(AsmVisitorWrapper asmVisitorWrapper);

        /**

         * Names the dynamic type by the supplied name. The name needs to be fully qualified and in the binary format (packages separated

         * by dots: {@code foo.Bar}). A type's package determines what other types are visible to the instrumented type and what methods

         * can be overridden or be represented in method signatures or as field types.

         *

         * @param name The fully qualified name of the generated class in a binary format.

         * @return A new builder that is equal to this builder but with the instrumented type named by the supplied name.

         */

        Builder<T> name(String name);

        /**

         * Adds a suffix to the current type name without changing the type's package.

         *

         * @param suffix The suffix to append to the current type name.

         * @return A new builder that is equal to this builder but with the instrumented type named suffixed by the supplied suffix.

         */

        Builder<T> suffix(String suffix);

        /**

         * Defines the supplied modifiers as the modifiers of the instrumented type.

         *

         * @param modifierContributor The modifiers of the instrumented type.

         * @return A new builder that is equal to this builder but with the supplied modifiers applied onto the instrumented type.

         */

        Builder<T> modifiers(ModifierContributor.ForType... modifierContributor);

        /**

         * Defines the supplied modifiers as the modifiers of the instrumented type.

         *

         * @param modifierContributors The modifiers of the instrumented type.

         * @return A new builder that is equal to this builder but with the supplied modifiers applied onto the instrumented type.

         */

        Builder<T> modifiers(Collection<? extends ModifierContributor.ForType> modifierContributors);

        /**

         * Defines the supplied modifiers as the modifiers of the instrumented type.

         *

         * @param modifiers The modifiers of the instrumented type.

         * @return A new builder that is equal to this builder but with the supplied modifiers applied onto the instrumented type.

         */

        Builder<T> modifiers(int modifiers);

        /**

         * Merges the supplied modifier contributors with the modifiers of the instrumented type and defines them as the instrumented

         * type's new modifiers.

         *

         * @param modifierContributor The modifiers of the instrumented type.

         * @return A new builder that is equal to this builder but with the supplied modifiers merged into the instrumented type's modifiers.

         */

        Builder<T> merge(ModifierContributor.ForType... modifierContributor);

        /**

         * Merges the supplied modifier contributors with the modifiers of the instrumented type and defines them as the instrumented

         * type's new modifiers.

         *

         * @param modifierContributors The modifiers of the instrumented type.

         * @return A new builder that is equal to this builder but with the supplied modifiers merged into the instrumented type's modifiers.

         */

        Builder<T> merge(Collection<? extends ModifierContributor.ForType> modifierContributors);

        /**

         * <p>

         * Defines this type as a top-level type that is not declared by another type or enclosed by another member.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @return A new builder that is equal to this builder but without any declaration of a declared or enclosed type.

         */

        Builder<T> topLevelType();

        /**

         * <p>

         * Defines this type as an inner type of the supplied type. Without any additional configuration, the type declaration is defined

         * as a local type.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The type to declare as the built type's outer type.

         * @return A new builder that is equal to this builder with the supplied type as the built type's outer type.

         */

        InnerTypeDefinition.ForType<T> innerTypeOf(Class<?> type);

        /**

         * <p>

         * Defines this type as an inner type of the supplied type. Without any additional configuration, the type declaration is

         * defined as a local type.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The type to declare as the built type's outer type.

         * @return A new builder that is equal to this builder with the supplied type as the built type's outer type.

         */

        InnerTypeDefinition.ForType<T> innerTypeOf(TypeDescription type);

        /**

         * <p>

         * Defines this type as an inner type that was declared within the supplied method.  Without any additional configuration, the type

         * declaration is defined as a local type.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param method The method to declare as the built type's declaring method.

         * @return A new builder that is equal to this builder with the supplied method as the built type's declaring method.

         */

        InnerTypeDefinition<T> innerTypeOf(Method method);

        /**

         * <p>

         * Defines this type as an inner type that was declared within the supplied constructor. Without any additional configuration, the type

         * declaration is defined as a local type.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param constructor The constructor to declare as the built type's declaring method.

         * @return A new builder that is equal to this builder with the supplied method as the built type's declaring constructor.

         */

        InnerTypeDefinition<T> innerTypeOf(Constructor<?> constructor);

        /**

         * <p>

         * Defines this type as an inner type that was declared within the supplied method or constructor. Without any additional configuration,

         * the type declaration is defined as a local type.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param methodDescription The method or constructor to declare as the built type's declaring method.

         * @return A new builder that is equal to this builder with the supplied method as the built type's declaring method or constructor.

         */

        InnerTypeDefinition<T> innerTypeOf(MethodDescription.InDefinedShape methodDescription);

        /**

         * <p>

         * Defines this type as an the outer type of the supplied types. Using this method, it is possible to add inner type declarations

         * for anonymous or local types which are not normally exposed by type descriptions. Doing so, it is however possible to indicate to

         * Byte Buddy that the required attributes for such an inner type declaration should be added to a class file.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The types being declared.

         * @return A new builder that is equal to this builder with the supplied types being declared by the built type.

         */

        Builder<T> declaredTypes(Class<?>... type);

        /**

         * <p>

         * Defines this type as an the outer type of the supplied types. Using this method, it is possible to add inner type declarations

         * for anonymous or local types which are not normally exposed by type descriptions. Doing so, it is however possible to indicate to

         * Byte Buddy that the required attributes for such an inner type declaration should be added to a class file.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The types being declared.

         * @return A new builder that is equal to this builder with the supplied types being declared by the built type.

         */

        Builder<T> declaredTypes(TypeDescription... type);

        /**

         * <p>

         * Defines this type as an the outer type of the supplied types. Using this method, it is possible to add inner type declarations

         * for anonymous or local types which are not normally exposed by type descriptions. Doing so, it is however possible to indicate to

         * Byte Buddy that the required attributes for such an inner type declaration should be added to a class file.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param types The types being declared.

         * @return A new builder that is equal to this builder with the supplied types being declared by the built type.

         */

        Builder<T> declaredTypes(List<? extends Class<?>> types);

        /**

         * <p>

         * Defines this type as an the outer type of the supplied types. Using this method, it is possible to add inner type declarations

         * for anonymous or local types which are not normally exposed by type descriptions. Doing so, it is however possible to indicate to

         * Byte Buddy that the required attributes for such an inner type declaration should be added to a class file.

         * </p>

         * <p>

         * <b>Important</b>: Changing the declaration hierarchy of a type has no influence on the nest mate hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: By changing this type's declaration, any other type will not change its declaration of enclosing members or

         * declared types about any nesting of a declaration. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param types The types being declared.

         * @return A new builder that is equal to this builder with the supplied types being declared by the built type.

         */

        Builder<T> declaredTypes(Collection<? extends TypeDescription> types);

        /**

         * <p>

         * Defines this type as self-hosted, i.e. as only being a nest mate of itself.

         * </p>

         * <p>

         * <b>Important</b>: Changing the nest mate hierarchy of a type has no influence on the declaration hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: Changing nest mate hierarchies always requires changing a member and its host or a host and all its members.

         * Otherwise, the runtime will not accept further nest mates. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @return A new builder that is equal to this builder but where the built type is a self-hosted nest mate.

         */

        Builder<T> noNestMate();

        /**

         * <p>

         * Defines this type as a nest member of the supplied type as a nest host.

         * </p>

         * <p>

         * <b>Important</b>: Changing the nest mate hierarchy of a type has no influence on the declaration hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: Changing nest mate hierarchies always requires changing a member and its host or a host and all its members.

         * Otherwise, the runtime will not accept further nest mates. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The nest host.

         * @return A new builder that is equal to this builder but where the built type is a nest member of the supplied host.

         */

        Builder<T> nestHost(Class<?> type);

        /**

         * <p>

         * Defines this type as a nest member of the supplied type as a nest host.

         * </p>

         * <p>

         * <b>Important</b>: Changing the nest mate hierarchy of a type has no influence on the declaration hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: Changing nest mate hierarchies always requires changing a member and its host or a host and all its members.

         * Otherwise, the runtime will not accept further nest mates. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The nest host.

         * @return A new builder that is equal to this builder but where the built type is a nest member of the supplied host.

         */

        Builder<T> nestHost(TypeDescription type);

        /**

         * <p>

         * Defines this type as a nest host for the supplied types.

         * </p>

         * <p>

         * <b>Important</b>: Changing the nest mate hierarchy of a type has no influence on the declaration hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: Changing nest mate hierarchies always requires changing a member and its host or a host and all its members.

         * Otherwise, the runtime will not accept further nest mates. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The nest members.

         * @return A new builder that is equal to this builder but where the built type is a nest host of the supplied types.

         */

        Builder<T> nestMembers(Class<?>... type);

        /**

         * <p>

         * Defines this type as a nest host for the supplied types.

         * </p>

         * <p>

         * <b>Important</b>: Changing the nest mate hierarchy of a type has no influence on the declaration hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: Changing nest mate hierarchies always requires changing a member and its host or a host and all its members.

         * Otherwise, the runtime will not accept further nest mates. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param type The nest members.

         * @return A new builder that is equal to this builder but where the built type is a nest host of the supplied types.

         */

        Builder<T> nestMembers(TypeDescription... type);

        /**

         * <p>

         * Defines this type as a nest host for the supplied types.

         * </p>

         * <p>

         * <b>Important</b>: Changing the nest mate hierarchy of a type has no influence on the declaration hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: Changing nest mate hierarchies always requires changing a member and its host or a host and all its members.

         * Otherwise, the runtime will not accept further nest mates. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param types The nest members.

         * @return A new builder that is equal to this builder but where the built type is a nest host of the supplied types.

         */

        Builder<T> nestMembers(List<? extends Class<?>> types);

        /**

         * <p>

         * Defines this type as a nest host for the supplied types.

         * </p>

         * <p>

         * <b>Important</b>: Changing the nest mate hierarchy of a type has no influence on the declaration hierarchy.

         * </p>

         * <p>

         * <b>Warning</b>: Changing nest mate hierarchies always requires changing a member and its host or a host and all its members.

         * Otherwise, the runtime will not accept further nest mates. It is the responsibility of the user of this API to keep such declarations

         * consistent among the definitions of connected types.

         * </p>

         *

         * @param types The nest members.

         * @return A new builder that is equal to this builder but where the built type is a nest host of the supplied types.

         */

        Builder<T> nestMembers(Collection<? extends TypeDescription> types);

        /**

         * Defines this type to allow the supplied permitted subclasses additionally to any prior permitted subclasses. If

         * this type was not previously sealed, only the supplied subclasses are permitted.

         *

         * @param type The permitted subclasses.

         * @return A new builder that is equal to this builder but where the built type permits the supplied subclasses.

         */

        Builder<T> permittedSubclass(Class<?>... type);

        /**

         * Defines this type to allow the supplied permitted subclasses additionally to any prior permitted subclasses. If

         * this type was not previously sealed, only the supplied subclasses are permitted.

         *

         * @param type The permitted subclasses.

         * @return A new builder that is equal to this builder but where the built type permits the supplied subclasses.

         */

        Builder<T> permittedSubclass(TypeDescription... type);

        /**

         * Defines this type to allow the supplied permitted subclasses additionally to any prior permitted subclasses. If

         * this type was not previously sealed, only the supplied subclasses are permitted.

         *

         * @param types The permitted subclasses.

         * @return A new builder that is equal to this builder but where the built type permits the supplied subclasses.

         */

        Builder<T> permittedSubclass(List<? extends Class<?>> types);

        /**

         * Defines this type to allow the supplied permitted subclasses additionally to any prior permitted subclasses. If

         * this type was not previously sealed, only the supplied subclasses are permitted.

         *

         * @param types The permitted subclasses.

         * @return A new builder that is equal to this builder but where the built type permits the supplied subclasses.

         */

        Builder<T> permittedSubclass(Collection<? extends TypeDescription> types);

        /**

         * Unseales this type.

         *

         * @return A new builder that is equal to this builder but where the built type does not restrain its permitted subclasses.

         */

        Builder<T> unsealed();

        /**

         * Applies the given type attribute appender onto the instrumented type. Using a type attribute appender, it is possible to append

         * any type of meta data to a type, not only Java {@link Annotation}s.

         *

         * @param typeAttributeAppender The type attribute appender to apply.

         * @return A new builder that is equal to this builder but with the supplied type attribute appender applied to the instrumented type.

         */

        Builder<T> attribute(TypeAttributeAppender typeAttributeAppender);

        /**

         * Annotates the instrumented type with the supplied annotations.

         *

         * @param annotation The annotations to add to the instrumented type.

         * @return A new builder that is equal to this builder but with the annotations added to the instrumented type.

         */

        Builder<T> annotateType(Annotation... annotation);

        /**

         * Annotates the instrumented type with the supplied annotations.

         *

         * @param annotations The annotations to add to the instrumented type.

         * @return A new builder that is equal to this builder but with the annotations added to the instrumented type.

         */

        Builder<T> annotateType(List<? extends Annotation> annotations);

        /**

         * Annotates the instrumented type with the supplied annotations.

         *

         * @param annotation The annotations to add to the instrumented type.

         * @return A new builder that is equal to this builder but with the annotations added to the instrumented type.

         */

        Builder<T> annotateType(AnnotationDescription... annotation);

        /**

         * Annotates the instrumented type with the supplied annotations.

         *

         * @param annotations The annotations to add to the instrumented type.

         * @return A new builder that is equal to this builder but with the annotations added to the instrumented type.

         */

        Builder<T> annotateType(Collection<? extends AnnotationDescription> annotations);

        /**

         * <p>

         * Implements the supplied interfaces for the instrumented type. Optionally, it is possible to define the

         * methods that are defined by the interfaces or the interfaces' super interfaces. This excludes methods that

         * are explicitly ignored.

         * </p>

         * <p>

         * <b>Note</b>: This methods implements the supplied types <i>as is</i>, i.e. any {@link Class} values are implemented

         * as raw types if they declare type variables or an owner type.

         * </p>

         *

         * @param interfaceType The interface types to implement.

         * @return A new builder that is equal to this builder but with the interfaces implemented by the instrumented type.

         */

        MethodDefinition.ImplementationDefinition.Optional<T> implement(Type... interfaceType);

        /**

         * <p>

         * Implements the supplied interfaces for the instrumented type. Optionally, it is possible to define the

         * methods that are defined by the interfaces or the interfaces' super interfaces. This excludes methods that

         * are explicitly ignored.

         * </p>

         * <p>

         * <b>Note</b>: This methods implements the supplied types <i>as is</i>, i.e. any {@link Class} values are implemented

         * as raw types if they declare type variables or an owner type.

         * </p>

         *

         * @param interfaceTypes The interface types to implement.

         * @return A new builder that is equal to this builder but with the interfaces implemented by the instrumented type.

         */

        MethodDefinition.ImplementationDefinition.Optional<T> implement(List<? extends Type> interfaceTypes);

        /**

         * <p>

         * Implements the supplied interfaces for the instrumented type. Optionally, it is possible to define the

         * methods that are defined by the interfaces or the interfaces' super interfaces. This excludes methods that

         * are explicitly ignored.

         * </p>

         * <p>

         * <b>Note</b>: This methods implements the supplied types <i>as is</i>, i.e. any {@link TypeDescription} values are

         * implemented as raw types if they declare type variables or an owner type.

         * </p>

         *

         * @param interfaceType The interface types to implement.

         * @return A new builder that is equal to this builder but with the interfaces implemented by the instrumented type.

         */

        MethodDefinition.ImplementationDefinition.Optional<T> implement(TypeDefinition... interfaceType);

        /**

         * <p>

         * Implements the supplied interfaces for the instrumented type. Optionally, it is possible to define the

         * methods that are defined by the interfaces or the interfaces' super interfaces. This excludes methods that

         * are explicitly ignored.

         * </p>

         * <p>

         * <b>Note</b>: This methods implements the supplied types <i>as is</i>, i.e. any {@link TypeDescription} values are

         * implemented as raw types if they declare type variables or an owner type.

         * </p>

         *

         * @param interfaceTypes The interface types to implement.

         * @return A new builder that is equal to this builder but with the interfaces implemented by the instrumented type.

         */

        MethodDefinition.ImplementationDefinition.Optional<T> implement(Collection<? extends TypeDefinition> interfaceTypes);

        /**

         * <p>

         * Executes the supplied byte code appender within the beginning of the instrumented type's type initializer. The

         * supplied byte code appender <b>must not return</b> from the method. If several byte code appenders are supplied,

         * they are executed within their application order.

         * </p>

         * <p>

         * This method should only be used for preparing an instrumented type with a specific configuration. Normally,

         * a byte code appender is applied via Byte Buddy's standard API by invoking {@link Builder#invokable(ElementMatcher)}

         * using the {@link net.bytebuddy.matcher.ElementMatchers#isTypeInitializer()} matcher.

         * </p>

         *

         * @param byteCodeAppender The byte code appender to execute within the instrumented type's type initializer.

         * @return A new builder that is equal to this builder but with the supplied byte code appender being executed within

         * the instrumented type's type initializer.

         */

        Builder<T> initializer(ByteCodeAppender byteCodeAppender);

        /**

         * Executes the supplied loaded type initializer when loading the created instrumented type. If several loaded

         * type initializers are supplied, each loaded type initializer is executed in its registration order.

         *

         * @param loadedTypeInitializer The loaded type initializer to execute upon loading the instrumented type.

         * @return A new builder that is equal to this builder but with the supplied loaded type initializer executed upon

         * loading the instrumented type.

         */

        Builder<T> initializer(LoadedTypeInitializer loadedTypeInitializer);

        /**

         * Explicitly requires another dynamic type for the creation of this type.

         *

         * @param type                 The type to require.

         * @param binaryRepresentation The type's binary representation.

         * @return A new builder that is equal to this builder but which explicitly requires the supplied type.

         */

        Builder<T> require(TypeDescription type, byte[] binaryRepresentation);

        /**

         * Explicitly requires another dynamic type for the creation of this type.

         *

         * @param type                 The type to require.

         * @param binaryRepresentation The type's binary representation.

         * @param typeInitializer      The type's loaded type initializer.

         * @return A new builder that is equal to this builder but which explicitly requires the supplied type.

         */

        Builder<T> require(TypeDescription type, byte[] binaryRepresentation, LoadedTypeInitializer typeInitializer);

        /**

         * Explicitly requires other dynamic types for the creation of this type.

         *

         * @param auxiliaryType The required dynamic types.

         * @return A new builder that is equal to this builder but which explicitly requires the supplied types.

         */

        Builder<T> require(DynamicType... auxiliaryType);

        /**

         * Explicitly requires other dynamic types for the creation of this type.

         *

         * @param auxiliaryTypes The required dynamic types.

         * @return A new builder that is equal to this builder but which explicitly requires the supplied types.

         */

        Builder<T> require(Collection<DynamicType> auxiliaryTypes);

        /**

         * Defines the supplied type variable without any bounds as a type variable of the instrumented type.

         *

         * @param symbol The type variable's symbol.

         * @return A new builder that is equal to this builder but with the given type variable defined for the instrumented type.

         */

        TypeVariableDefinition<T> typeVariable(String symbol);

        /**

         * Defines the supplied type variable with the given bound as a type variable of the instrumented type.

         *

         * @param symbol The type variable's symbol.

         * @param bound  The type variable's upper bounds. Can also be {@link net.bytebuddy.dynamic.TargetType} if the bound type

         *               should be equal to the currently instrumented type.

         * @return A new builder that is equal to this builder but with the given type variable defined for the instrumented type.

         */

        TypeVariableDefinition<T> typeVariable(String symbol, Type... bound);

        /**

         * Defines the supplied type variable with the given bound as a type variable of the instrumented type.

         *

         * @param symbol The type variable's symbol.

         * @param bounds The type variable's upper bounds. Can also be {@link net.bytebuddy.dynamic.TargetType} if the bound type

         *               should be equal to the currently instrumented type.

         * @return A new builder that is equal to this builder but with the given type variable defined for the instrumented type.

         */

        TypeVariableDefinition<T> typeVariable(String symbol, List<? extends Type> bounds);

        /**

         * Defines the supplied type variable with the given bound as a type variable of the instrumented type.

         *

         * @param symbol The type variable's symbol.

         * @param bound  The type variable's upper bounds. Can also be {@link net.bytebuddy.dynamic.TargetType} if the bound type

         *               should be equal to the currently instrumented type.

         * @return A new builder that is equal to this builder but with the given type variable defined for the instrumented type.

         */

        TypeVariableDefinition<T> typeVariable(String symbol, TypeDefinition... bound);

        /**

         * Defines the supplied type variable with the given bound as a type variable of the instrumented type.

         *

         * @param symbol The type variable's symbol.

         * @param bounds The type variable's upper bounds. Can also be {@link net.bytebuddy.dynamic.TargetType} if the bound type

         *               should be equal to the currently instrumented type.

         * @return A new builder that is equal to this builder but with the given type variable defined for the instrumented type.

         */

        TypeVariableDefinition<T> typeVariable(String symbol, Collection<? extends TypeDefinition> bounds);

        /**

         * Transforms any type variable that is defined by this type if it is matched by the supplied matcher.

         *

         * @param matcher     The matcher to decide what type variables to transform.

         * @param transformer The transformer to apply to the matched type variables.

         * @return A new builder that is equal to this builder but with the supplied transformer applied to all type variables.

         */

        Builder<T> transform(ElementMatcher<? super TypeDescription.Generic> matcher, Transformer<TypeVariableToken> transformer);

        /**

         * Defines the specified field as a field of the built dynamic type.

         *

         * @param name                The name of the field.

         * @param type                The type of the field. Can also be {@link net.bytebuddy.dynamic.TargetType} if the field type

         *                            should be equal to the currently instrumented type.

         * @param modifierContributor The modifiers of the field.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> defineField(String name, Type type, ModifierContributor.ForField... modifierContributor);

        /**

         * Defines the specified field as a field of the built dynamic type.

         *

         * @param name                 The name of the field.

         * @param type                 The type of the field. Can also be {@link net.bytebuddy.dynamic.TargetType} if the field type

         *                             should be equal to the currently instrumented type.

         * @param modifierContributors The modifiers of the field.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> defineField(String name, Type type, Collection<? extends ModifierContributor.ForField> modifierContributors);

        /**

         * Defines the specified field as a field of the built dynamic type.

         *

         * @param name      The name of the field.

         * @param type      The type of the field. Can also be {@link net.bytebuddy.dynamic.TargetType} if the field type

         *                  should be equal to the currently instrumented type.

         * @param modifiers The modifiers of the field.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> defineField(String name, Type type, int modifiers);

        /**

         * Defines the specified field as a field of the built dynamic type.

         *

         * @param name                The name of the field.

         * @param type                The type of the field. Can also be {@link net.bytebuddy.dynamic.TargetType} if the field type

         *                            should be equal to the currently instrumented type.

         * @param modifierContributor The modifiers of the field.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> defineField(String name, TypeDefinition type, ModifierContributor.ForField... modifierContributor);

        /**

         * Defines the specified field as a field of the built dynamic type.

         *

         * @param name                 The name of the field.

         * @param type                 The type of the field. Can also be {@link net.bytebuddy.dynamic.TargetType} if the field type

         *                             should be equal to the currently instrumented type.

         * @param modifierContributors The modifiers of the field.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> defineField(String name, TypeDefinition type, Collection<? extends ModifierContributor.ForField> modifierContributors);

        /**

         * Defines the specified field as a field of the built dynamic type.

         *

         * @param name      The name of the field.

         * @param type      The type of the field. Can also be {@link net.bytebuddy.dynamic.TargetType} if the field type

         *                  should be equal to the currently instrumented type.

         * @param modifiers The modifiers of the field.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> defineField(String name, TypeDefinition type, int modifiers);

        /**

         * Defines a field that is similar to the supplied field but without copying any annotations on the field.

         *

         * @param field The field to imitate as a field of the instrumented type.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> define(Field field);

        /**

         * Defines a field that is similar to the supplied field but without copying any annotations on the field.

         *

         * @param field The field to imitate as a field of the instrumented type.

         * @return A new builder that is equal to this builder but with the given field defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional.Valuable<T> define(FieldDescription field);

        /**

         * Defines a private, static, final field for a serial version UID of the given value.

         *

         * @param serialVersionUid The serial version UID to define as a value.

         * @return A new builder that is equal to this builder but with the given type variable defined for the instrumented type.

         * Furthermore, it is possible to optionally define a value, annotations or custom attributes for the field.

         */

        FieldDefinition.Optional<T> serialVersionUid(long serialVersionUid);

        /**

         * <p>

         * Matches a field that is already declared by the instrumented type. This gives opportunity to change that field's

         * default value, annotations or custom attributes.

         * </p>

         * <p>

         * When a type is redefined or rebased, any annotations that the field declared previously is preserved

         * <i>as it is</i> if Byte Buddy is configured to retain such annotations by

         * {@link net.bytebuddy.implementation.attribute.AnnotationRetention#ENABLED}. If any existing annotations should be

         * altered, annotation retention must be disabled.

         * </p>

         * <p>

         * If a field is already matched by a previously specified field matcher, the new field definition gets precedence

         * over the previous definition, i.e. the previous field definition is no longer applied.

         * </p>

         *

         * @param matcher The matcher that determines what declared fields are affected by the subsequent specification.

         * @return A builder that allows for changing a field's definition.

         */

        @SuppressWarnings("overloads")

        FieldDefinition.Valuable<T> field(ElementMatcher<? super FieldDescription> matcher);

        /**

         * <p>

         * Matches a field that is already declared by the instrumented type. This gives opportunity to change that field's

         * default value, annotations or custom attributes. Using a latent matcher gives opportunity to resolve an

         * {@link ElementMatcher} based on the instrumented type before applying the matcher.

         * </p>

         * <p>

         * When a type is redefined or rebased, any annotations that the field declared previously is preserved

         * <i>as it is</i> if Byte Buddy is configured to retain such annotations by