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
015package 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 */
045public 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}