    001    // Copyright 2006, 2007, 2010 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    // http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5.ioc.services;
    016
    017    import org.apache.tapestry5.ioc.Location;
    018    import org.apache.tapestry5.ioc.ObjectCreator;
    019
    020    import java.lang.reflect.Constructor;
    021    import java.lang.reflect.Method;
    022
    023    /**
    024     * Service used when dynamically creating new classes.
    025     *
    026     * @deprecated In 5.3, use {@link PlasticProxyFactory} instead
    027     */
    028    public interface ClassFactory
    029    {
    030        /**
    031         * Simplified version of {@link #newClass(String, Class)} that generates a name based on the service interface name,
    032         * extends from java.lang.Object, and automatically adds the serviceInterface to the returned ClassFab. This is the
    033         * most common use when creating the kinds of proxies used throughout Tapestry IoC.
    034         *
    035         * @param serviceInterface
    036         */
    037        ClassFab newClass(Class serviceInterface);
    038
    039        /**
    040         * Creates a {@link ClassFab} object for the given name; the new class is a subclass of the indicated class. The new
    041         * class is always public and concrete.
    042         *
    043         * @param name
    044         *            the full qualified name of the class to create (note that it is common to place created classes
    045         *            in the default package)
    046         * @param superClass
    047         *            the parent class, which is often java.lang.Object
    048         */
    049
    050        ClassFab newClass(String name, Class superClass);
    051
    052        /**
    053         * Imports the class to make it referenceable within the factory. The class loader for the class is added to the
    054         * class path. The class itself is returned, if its bytecode is available. If not, a search up the inhertance occurs
    055         * until a proper class (that can be referenced in generated bytecode) is found. This is necessary to handle cases
    056         * where a class is generated at runtime, outside of the class factory, and bytecode is not available for it.
    057         *
    058         * @param clazz
    059         * @return a referenceable super-class
    060         */
    061        Class importClass(Class clazz);
    062
    063        /**
    064         * Returns the number of classes (and interfaces) actually created.
    065         */
    066
    067        int getCreatedClassCount();
    068
    069        /**
    070         * Returns the class loader used when creating new classes; this is generally the same as the current thread's
    071         * context class loader (except perhaps during testing).
    072         */
    073        ClassLoader getClassLoader();
    074
    075        /**
    076         * Converts a method to a {@link Location}, which includes information about the source file name and line number.
    077         *
    078         * @param method
    079         *            to look up
    080         * @return the location, or null if the necessary information is not available
    081         */
    082        Location getMethodLocation(Method method);
    083
    084        /**
    085         * Return a string representation for the constructor (including class and parameters) and (if available) file name
    086         * and line number.
    087         */
    088        Location getConstructorLocation(Constructor constructor);
    089
    090        /**
    091         * Creates a proxy for an interface. All methods of the interface are delegated through the
    092         * object returned from the {@link ObjectCreator} (which is accessed on each method invocation, so it
    093         * is responsible for caching of the true delegate). The description will be used for the toString() method
    094         * (unless toString() is part of the proxy interface).
    095         *
    096         * @param <T>
    097         *            type of proxy
    098         * @param proxyInterface
    099         *            proxy interface class
    100         * @param delegateCreator
    101         *         creates the delegate
    102         * @param description
    103         *            used for the toString() method
    104         * @since 5.2.0
    105         */
    106        <T> T createProxy(Class<T> proxyInterface, ObjectCreator delegateCreator, String description);
    107
    108        /**
    109         * Creates a proxy for an interface. All methods of the interface are delegated through the
    110         * object returned from the {@link ObjectCreator} (which is accessed on each method invocation, so it
    111         * is responsible for caching of the true delegate). The description will be used for the toString() method
    112         * (unless toString() is part of the proxy interface).
    113         *
    114         * @param <T>
    115         *            type of proxy
    116         * @param proxyInterface
    117         *            proxy interface class
    118         * @param delegateClass
    119         *         delegate class
    120         * @param delegateCreator
    121         *         creates the delegate
    122         * @param description
    123         *            used for the toString() method
    124         * @since 5.2.0
    125         */
    126        <T> T createProxy(Class<T> proxyInterface, Class<? extends T> delegateClass, ObjectCreator delegateCreator,
    127                String description);
    128    }