    001    // Copyright 2011, 2012 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    import org.apache.tapestry5.plastic.ClassInstantiator;
    020    import org.apache.tapestry5.plastic.PlasticClassListenerHub;
    021    import org.apache.tapestry5.plastic.PlasticClassTransformation;
    022    import org.apache.tapestry5.plastic.PlasticClassTransformer;
    023
    024    import java.lang.reflect.Constructor;
    025    import java.lang.reflect.Method;
    026
    027    /**
    028     * A service used to create proxies of varying types. As a secondary concern, manages to identify the
    029     * location of methods and constructors, which is important for exception reporting.
    030     *
    031     * @since 5.3
    032     */
    033    public interface PlasticProxyFactory extends PlasticClassListenerHub
    034    {
    035        /**
    036         * Returns the class loader used when creating new classes, this is a child class loader
    037         * of another class loader (usually, the thread's context class loader).
    038         */
    039        ClassLoader getClassLoader();
    040
    041        /**
    042         * Creates a proxy object that implements the indicated interface, then invokes the callback to further
    043         * configure the proxy.
    044         *
    045         * @param interfaceType
    046         *         interface implemented by proxy
    047         * @param callback
    048         *         configures the proxy
    049         * @return instantiator that can be used to create an instance of the proxy class
    050         */
    051        <T> ClassInstantiator<T> createProxy(Class<T> interfaceType, PlasticClassTransformer callback);
    052
    053        /**
    054         * Creates the underlying {@link PlasticClassTransformation} for an interface proxy. This should only be
    055         * used in the cases where encapsulating the PlasticClass construction into a {@linkplain PlasticClassTransformer
    056         * callback} is not feasible (which is the case for some of the older APIs inside Tapestry IoC).
    057         *
    058         * @param interfaceType
    059         *         class proxy will extend from
    060         * @return transformation from which an instantiator may be created
    061         */
    062        <T> PlasticClassTransformation<T> createProxyTransformation(Class<T> interfaceType);
    063
    064        /**
    065         * Creates a proxy instance that delegates all methods through a corresponding
    066         * ObjectCreator. Each method invocation on the proxy will route through {@link ObjectCreator#createObject()} (the
    067         * creator implementation may decide to
    068         * cache the return value as appropriate).
    069         *
    070         * @param <T>
    071         *         type of proxy
    072         * @param interfaceType
    073         *         interface class for proxy
    074         * @param creator
    075         *         object responsible for creating the real object
    076         * @param description
    077         *         the <code>toString()</code> of the proxy
    078         * @return proxy instance
    079         */
    080        <T> T createProxy(Class<T> interfaceType, ObjectCreator<T> creator, String description);
    081
    082        /**
    083         * Converts a method to a {@link Location}, which includes information about the source file name and line number.
    084         *
    085         * @param method
    086         *         to look up
    087         * @return the location (identifying the method and possibly, the line number within the method)
    088         */
    089        Location getMethodLocation(Method method);
    090
    091        /**
    092         * Return a string representation for the constructor (including class and parameters) and (if available) file name
    093         * and line number.
    094         *
    095         * @return the location (identifying the constructor and possibly, the line number within the method)
    096         */
    097        Location getConstructorLocation(Constructor constructor);
    098
    099        /**
    100         * Clears any cached information stored by the proxy factory; this is useful in Tapestry development mode
    101         * when a class loader may have been discarded (because the proxy factory may indirectly keep references
    102         * to classes loaded by the old class loader).
    103         *
    104         * @since 5.3.3
    105         */
    106        void clearCache();
    107    }