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 }