| // Copyright 2011, 2012 The Apache Software Foundation |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package org.apache.tapestry5.ioc.services; |
| |
| import org.apache.tapestry5.ioc.Location; |
| import org.apache.tapestry5.ioc.ObjectCreator; |
| import org.apache.tapestry5.ioc.annotations.IncompatibleChange; |
| import org.apache.tapestry5.plastic.ClassInstantiator; |
| import org.apache.tapestry5.plastic.PlasticClassListenerHub; |
| import org.apache.tapestry5.plastic.PlasticClassTransformation; |
| import org.apache.tapestry5.plastic.PlasticClassTransformer; |
| |
| import java.lang.reflect.Constructor; |
| import java.lang.reflect.Method; |
| |
| /** |
| * A service used to create proxies of varying types. As a secondary concern, manages to identify the |
| * location of methods and constructors, which is important for exception reporting. |
| * |
| * @since 5.3 |
| */ |
| public interface PlasticProxyFactory extends PlasticClassListenerHub |
| { |
| /** |
| * Returns the class loader used when creating new classes, this is a child class loader |
| * of another class loader (usually, the thread's context class loader). |
| */ |
| ClassLoader getClassLoader(); |
| |
| /** |
| * Creates a proxy object that implements the indicated interface, then invokes the callback to further |
| * configure the proxy. |
| * |
| * @param interfaceType |
| * interface implemented by proxy |
| * @param callback |
| * configures the proxy |
| * @return instantiator that can be used to create an instance of the proxy class |
| */ |
| <T> ClassInstantiator<T> createProxy(Class<T> interfaceType, PlasticClassTransformer callback); |
| |
| /** |
| * Creates a proxy object that implements the indicated interface and indicated service implementation type, |
| * then invokes the callback to further configure the proxy. |
| * |
| * @param interfaceType |
| * interface implemented by proxy |
| * @param implementationType |
| * a class that implements the interfaceType. It can be null. |
| * @param callback |
| * configures the proxy |
| * @return instantiator that can be used to create an instance of the proxy class |
| */ |
| @IncompatibleChange(release = "5.4", details = "TAP5-2029") |
| <T> ClassInstantiator<T> createProxy(Class<T> interfaceType, Class<? extends T> implementationType, PlasticClassTransformer callback); |
| |
| /** |
| * Creates the underlying {@link PlasticClassTransformation} for an interface proxy. This should only be |
| * used in the cases where encapsulating the PlasticClass construction into a {@linkplain PlasticClassTransformer |
| * callback} is not feasible (which is the case for some of the older APIs inside Tapestry IoC). |
| * |
| * @param interfaceType |
| * class proxy will extend from |
| * @return transformation from which an instantiator may be created |
| */ |
| <T> PlasticClassTransformation<T> createProxyTransformation(Class<T> interfaceType); |
| |
| /** |
| * Creates the underlying {@link PlasticClassTransformation} for an interface proxy with a given |
| * implementation class. This should only be |
| * used in the cases where encapsulating the PlasticClass construction into a {@linkplain PlasticClassTransformer |
| * callback} is not feasible (which is the case for some of the older APIs inside Tapestry IoC). |
| * |
| * @param interfaceType |
| * class proxy will extend from |
| * @param implementationType |
| * a class that implements the interfaceType. It can be null. |
| * @return transformation from which an instantiator may be created |
| */ |
| @IncompatibleChange(release = "5.4", details = "TAP5-2029") |
| <T> PlasticClassTransformation<T> createProxyTransformation(Class<T> interfaceType, Class<? extends T> implementationType); |
| |
| /** |
| * Creates a proxy instance that delegates all methods through a corresponding |
| * ObjectCreator. Each method invocation on the proxy will route through {@link ObjectCreator#createObject()} (the |
| * creator implementation may decide to |
| * cache the return value as appropriate). |
| * |
| * @param <T> |
| * type of proxy |
| * @param interfaceType |
| * interface class for proxy |
| * @param creator |
| * object responsible for creating the real object |
| * @param description |
| * the <code>toString()</code> of the proxy |
| * @return proxy instance |
| */ |
| <T> T createProxy(Class<T> interfaceType, ObjectCreator<T> creator, String description); |
| |
| /** |
| * Creates a proxy instance that delegates all methods through a corresponding |
| * ObjectCreator. Each method invocation on the proxy will route through {@link ObjectCreator#createObject()} (the |
| * creator implementation may decide to |
| * cache the return value as appropriate). |
| * |
| * @param <T> |
| * type of proxy |
| * @param interfaceType |
| * interface class for proxy |
| * @param implementationType |
| * class that implements the interface type. It may be null |
| * @param creator |
| * object responsible for creating the real object |
| * @param description |
| * the <code>toString()</code> of the proxy |
| * @return proxy instance |
| */ |
| @IncompatibleChange(release = "5.4", details = "Added for TAP5-2029") |
| <T> T createProxy(Class<T> interfaceType, Class<? extends T> implementationType, ObjectCreator<T> creator, String description); |
| |
| /** |
| * Converts a method to a {@link Location}, which includes information about the source file name and line number. |
| * |
| * @param method |
| * to look up |
| * @return the location (identifying the method and possibly, the line number within the method) |
| */ |
| Location getMethodLocation(Method method); |
| |
| /** |
| * Return a string representation for the constructor (including class and parameters) and (if available) file name |
| * and line number. |
| * |
| * @return the location (identifying the constructor and possibly, the line number within the method) |
| */ |
| Location getConstructorLocation(Constructor constructor); |
| |
| /** |
| * Clears any cached information stored by the proxy factory; this is useful in Tapestry development mode |
| * when a class loader may have been discarded (because the proxy factory may indirectly keep references |
| * to classes loaded by the old class loader). |
| * |
| * @since 5.3.3 |
| */ |
| void clearCache(); |
| } |