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
015package org.apache.tapestry5.ioc.services;
016
017import org.apache.tapestry5.ioc.Location;
018import org.apache.tapestry5.ioc.ObjectCreator;
019import org.apache.tapestry5.plastic.ClassInstantiator;
020import org.apache.tapestry5.plastic.PlasticClassListenerHub;
021import org.apache.tapestry5.plastic.PlasticClassTransformation;
022import org.apache.tapestry5.plastic.PlasticClassTransformer;
023
024import java.lang.reflect.Constructor;
025import 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 */
033public 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}