001 // Copyright 2006, 2007, 2010 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
020 import java.lang.reflect.Constructor;
021 import java.lang.reflect.Method;
022
023 /**
024 * Service used when dynamically creating new classes.
025 *
026 * @deprecated In 5.3, use {@link PlasticProxyFactory} instead
027 */
028 public interface ClassFactory
029 {
030 /**
031 * Simplified version of {@link #newClass(String, Class)} that generates a name based on the service interface name,
032 * extends from java.lang.Object, and automatically adds the serviceInterface to the returned ClassFab. This is the
033 * most common use when creating the kinds of proxies used throughout Tapestry IoC.
034 *
035 * @param serviceInterface
036 */
037 ClassFab newClass(Class serviceInterface);
038
039 /**
040 * Creates a {@link ClassFab} object for the given name; the new class is a subclass of the indicated class. The new
041 * class is always public and concrete.
042 *
043 * @param name
044 * the full qualified name of the class to create (note that it is common to place created classes
045 * in the default package)
046 * @param superClass
047 * the parent class, which is often java.lang.Object
048 */
049
050 ClassFab newClass(String name, Class superClass);
051
052 /**
053 * Imports the class to make it referenceable within the factory. The class loader for the class is added to the
054 * class path. The class itself is returned, if its bytecode is available. If not, a search up the inhertance occurs
055 * until a proper class (that can be referenced in generated bytecode) is found. This is necessary to handle cases
056 * where a class is generated at runtime, outside of the class factory, and bytecode is not available for it.
057 *
058 * @param clazz
059 * @return a referenceable super-class
060 */
061 Class importClass(Class clazz);
062
063 /**
064 * Returns the number of classes (and interfaces) actually created.
065 */
066
067 int getCreatedClassCount();
068
069 /**
070 * Returns the class loader used when creating new classes; this is generally the same as the current thread's
071 * context class loader (except perhaps during testing).
072 */
073 ClassLoader getClassLoader();
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
079 * to look up
080 * @return the location, or null if the necessary information is not available
081 */
082 Location getMethodLocation(Method method);
083
084 /**
085 * Return a string representation for the constructor (including class and parameters) and (if available) file name
086 * and line number.
087 */
088 Location getConstructorLocation(Constructor constructor);
089
090 /**
091 * Creates a proxy for an interface. All methods of the interface are delegated through the
092 * object returned from the {@link ObjectCreator} (which is accessed on each method invocation, so it
093 * is responsible for caching of the true delegate). The description will be used for the toString() method
094 * (unless toString() is part of the proxy interface).
095 *
096 * @param <T>
097 * type of proxy
098 * @param proxyInterface
099 * proxy interface class
100 * @param delegateCreator
101 * creates the delegate
102 * @param description
103 * used for the toString() method
104 * @since 5.2.0
105 */
106 <T> T createProxy(Class<T> proxyInterface, ObjectCreator delegateCreator, String description);
107
108 /**
109 * Creates a proxy for an interface. All methods of the interface are delegated through the
110 * object returned from the {@link ObjectCreator} (which is accessed on each method invocation, so it
111 * is responsible for caching of the true delegate). The description will be used for the toString() method
112 * (unless toString() is part of the proxy interface).
113 *
114 * @param <T>
115 * type of proxy
116 * @param proxyInterface
117 * proxy interface class
118 * @param delegateClass
119 * delegate class
120 * @param delegateCreator
121 * creates the delegate
122 * @param description
123 * used for the toString() method
124 * @since 5.2.0
125 */
126 <T> T createProxy(Class<T> proxyInterface, Class<? extends T> delegateClass, ObjectCreator delegateCreator,
127 String description);
128 }