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
015package org.apache.tapestry5.ioc.services;
016
017import org.apache.tapestry5.ioc.Location;
018import org.apache.tapestry5.ioc.ObjectCreator;
019
020import java.lang.reflect.Constructor;
021import 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 */
028public 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}