    001    // Copyright 2006, 2007, 2011 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    /**
    018     * Used when fabricating a new class. Represents a wrapper around the Javassist library.
    019     * <p/>
    020     * The core concept of Javassist is how method bodies (as well as constructor bodies, etc.) are specified ... as a very
    021     * Java-like scripting language. Details are available at the <a href="http://jboss.org/products/javassist">Javassist
    022     * home page</a>.
    023     * <p/>
    024     * Method bodies look largely like Java. References to java classes must be fully qualified. Several special variables
    025     * are used:
    026     * <ul>
    027     * <li><code>$0</code> first parameter, equivalent to <code>this</code> in Java code (and can't be used when creating a
    028     * static method)
    029     * <li><code>$1, $2, ...</code> actual parameters to the method
    030     * <li><code>$args</code> all the parameters as an <code>Object[]</code>
    031     * <li><code>$r</code> the return type of the method, typically used as <code>return ($r) ...</code>. <code>$r</code> is
    032     * valid with method that return <code>void</code>. This also handles conversions between wrapper types and primitive
    033     * types.
    034     * <li><code>$w</code> conversion from primitive type to wrapper type, used as <code>($w) foo()</code> where
    035     * <code>foo()</code> returns a primitive type and a wrapper type is needed
    036     * <li>
    037     * </ul>
    038     * <p/>
    039     * ClassFab instances are not thread safe.
    040     * <p/>
    041     * ClassFab instances are created by a {@link org.apache.tapestry5.ioc.services.ClassFactory}.
    042     *
    043     * @deprecated In 5.3, use {@link PlasticProxyFactory} instead
    044     */
    045    public interface ClassFab
    046    {
    047        /**
    048         * Adds the specified interface as an interface implemented by this class. It is not an error to invoke this method
    049         * multiple times with the same interface class (and the interface is only added once).
    050         */
    051        void addInterface(Class interfaceClass);
    052
    053        /**
    054         * Adds a new field with the given name and type. The field is added as a private field.
    055         */
    056        void addField(String name, Class type);
    057
    058        /**
    059         * Adds a new field with the provided modifiers.
    060         */
    061        void addField(String name, int modifiers, Class Type);
    062
    063        /**
    064         * Adds a method. The method is a public instance method.
    065         *
    066         * @param modifiers
    067         *            Modifiers for the method (see {@link java.lang.reflect.Modifier}).
    068         * @param signature
    069         *            defines the name, return type, parameters and exceptions thrown
    070         * @param body
    071         *            The body of the method.
    072         * @throws RuntimeException
    073         *             if a method with that signature has already been added, or if there is a Javassist
    074         *             compilation error
    075         */
    076        void addMethod(int modifiers, MethodSignature signature, String body);
    077
    078        /**
    079         * Adds a constructor to the class. The constructor will be public.
    080         *
    081         * @param parameterTypes
    082         *            the type of each parameter, or null if the constructor takes no parameters.
    083         * @param exceptions
    084         *            the type of each exception, or null if the constructor throws no exceptions.
    085         * @param body
    086         *            The body of the constructor.
    087         */
    088        void addConstructor(Class[] parameterTypes, Class[] exceptions, String body);
    089
    090        /**
    091         * Adds an implementation of toString, as a method that returns a fixed string.
    092         */
    093        void addToString(String toString);
    094
    095        /**
    096         * Makes the fabricated class implement the provided service interface. The interface will be added, and all methods
    097         * in the interface will be delegate wrappers. If toString() is not part of the delegate interface, then an
    098         * implementation will be supplied that returns the provided string. This method is used when creating objects that
    099         * proxy their behavior to some other object.
    100         *
    101         * @param serviceInterface
    102         *            the interface to implement
    103         * @param delegateExpression
    104         *            the expression used to find the delegate on which methods should be invoked. Typically
    105         *            a field name, such as "_delegate", or a method to invoke, such as "_service()".
    106         * @param toString
    107         *            fixed value to be returned as the description of the resultant object
    108         */
    109        void proxyMethodsToDelegate(Class serviceInterface, String delegateExpression, String toString);
    110
    111        /**
    112         * Copies annotations from delegate class to the fabricated class.
    113         *
    114         * @param delegateClass
    115         *            class of the delegate
    116         * @since 5.2.0
    117         */
    118        void copyClassAnnotationsFromDelegate(Class delegateClass);
    119
    120        /**
    121         * Copies method annotations from delegate class to the methods of the fabricated class.
    122         *
    123         * @param serviceInterface
    124         *            service interface
    125         * @param delegateClass
    126         *            class of the delegate
    127         * @since 5.2.0
    128         */
    129        void copyMethodAnnotationsFromDelegate(Class serviceInterface, Class delegateClass);
    130
    131        /**
    132         * Invoked last to create the class. This will enforce that all abstract methods have been implemented in the
    133         * (concrete) class.
    134         */
    135        Class createClass();
    136
    137        /**
    138         * Adds a public no-op method. The method will return null, false, or zero as per the return type (if not void).
    139         */
    140
    141        void addNoOpMethod(MethodSignature signature);
    142    }