001 // Copyright 2011 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 interface implemented by proxy
046 * @param callback configures the proxy
047 * @return instantiator that can be used to create an instance of the proxy class
048 */
049 <T> ClassInstantiator<T> createProxy(Class<T> interfaceType, PlasticClassTransformer callback);
050
051 /**
052 * Creates the underlying {@link PlasticClassTransformation} for an interface proxy. This should only be
053 * used in the cases where encapsulating the PlasticClass construction into a {@linkplain PlasticClassTransformer
054 * callback} is not feasible (which is the case for some of the older APIs inside Tapestry IoC).
055 *
056 * @param interfaceType class proxy will extend from
057 * @return transformation from which an instantiator may be created
058 */
059 <T> PlasticClassTransformation<T> createProxyTransformation(Class<T> interfaceType);
060
061 /**
062 * Creates a proxy instance that delegates all methods through a corresponding
063 * ObjectCreator. Each method invocation on the proxy will route through {@link ObjectCreator#createObject()} (the
064 * creator implementation may decide to
065 * cache the return value as appropriate).
066 *
067 * @param <T> type of proxy
068 * @param interfaceType interface class for proxy
069 * @param creator object responsible for creating the real object
070 * @param description the <code>toString()</code> of the proxy
071 * @return proxy instance
072 */
073 <T> T createProxy(Class<T> interfaceType, ObjectCreator<T> creator, String description);
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 to look up
079 * @return the location (identifying the method and possibly, the line number within the method)
080 */
081 Location getMethodLocation(Method method);
082
083 /**
084 * Return a string representation for the constructor (including class and parameters) and (if available) file name
085 * and line number.
086 *
087 * @return the location (identifying the constructor and possibly, the line number within the method)
088 */
089 Location getConstructorLocation(Constructor constructor);
090 }