001    // Copyright 2006, 2007 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    
019    import java.lang.reflect.Constructor;
020    import java.lang.reflect.Method;
021    
022    /**
023     * Service used when dynamically creating new classes.
024     */
025    public interface ClassFactory
026    {
027        /**
028         * Simplified version of {@link #newClass(String, Class)} that generates a name based on the service interface name,
029         * extends from java.lang.Object, and automatically adds the serviceInterface to the returned ClassFab. This is the
030         * most common use when creating the kinds of proxies used throughout Tapestry IoC.
031         *
032         * @param serviceInterface
033         */
034        ClassFab newClass(Class serviceInterface);
035    
036        /**
037         * Creates a {@link ClassFab} object for the given name; the new class is a subclass of the indicated class. The new
038         * class is always public and concrete.
039         *
040         * @param name       the full qualified name of the class to create (note that it is common to place created classes
041         *                   in the default package)
042         * @param superClass the parent class, which is often java.lang.Object
043         */
044    
045        ClassFab newClass(String name, Class superClass);
046    
047        /**
048         * Imports the class to make it referenceable within the factory. The class loader for the class is added to the
049         * class path. The class itself is returned, if its bytecode is available. If not, a search up the inhertance occurs
050         * until a proper class (that can be referenced in generated bytecode) is found. This is necessary to handle cases
051         * where a class is generated at runtime, outside of the class factory, and bytecode is not available for it.
052         *
053         * @param clazz
054         * @return a referencable super-class
055         */
056        Class importClass(Class clazz);
057    
058        /**
059         * Returns the number of classes (and interfaces) actually created.
060         */
061    
062        int getCreatedClassCount();
063    
064        /**
065         * Returns the class loader used when creating new classes; this is generally the same as the current thread's
066         * context class loader (except perhaps during testing).
067         */
068        ClassLoader getClassLoader();
069    
070        /**
071         * Converts a method to a {@link Location}, which includes information about the source file name and line number.
072         *
073         * @param method to look up
074         * @return the location, or null if the necessary information is not available
075         */
076        Location getMethodLocation(Method method);
077    
078        /**
079         * Return a string representation fo the constructor (including class and parameters) and (if available) file name
080         * and line number.
081         */
082        Location getConstructorLocation(Constructor constructor);
083    }