001 // Copyright 2006, 2007, 2011 The Apache Software Foundation002 //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 at006 //007 // http://www.apache.org/licenses/LICENSE-2.0008 //009 // Unless required by applicable law or agreed to in writing, software010 // 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 and013 // limitations under the License.014015 package org.apache.tapestry5.ioc.services;016017 /**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 very021 * Java-like scripting language. Details are available at the <a href="http://jboss.org/products/javassist">Javassist022 * home page</a>.023 * <p/>024 * Method bodies look largely like Java. References to java classes must be fully qualified. Several special variables025 * 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 a028 * static method)029 * <li><code>$1, $2, ...</code> actual parameters to the method030 * <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> is032 * valid with method that return <code>void</code>. This also handles conversions between wrapper types and primitive033 * types.034 * <li><code>$w</code> conversion from primitive type to wrapper type, used as <code>($w) foo()</code> where035 * <code>foo()</code> returns a primitive type and a wrapper type is needed036 * <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} instead044 */045 public interface ClassFab046 {047 /**048 * Adds the specified interface as an interface implemented by this class. It is not an error to invoke this method049 * multiple times with the same interface class (and the interface is only added once).050 */051 void addInterface(Class interfaceClass);052053 /**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);057058 /**059 * Adds a new field with the provided modifiers.060 */061 void addField(String name, int modifiers, Class Type);062063 /**064 * Adds a method. The method is a public instance method.065 * 066 * @param modifiers067 * Modifiers for the method (see {@link java.lang.reflect.Modifier}).068 * @param signature069 * defines the name, return type, parameters and exceptions thrown070 * @param body071 * The body of the method.072 * @throws RuntimeException073 * if a method with that signature has already been added, or if there is a Javassist074 * compilation error075 */076 void addMethod(int modifiers, MethodSignature signature, String body);077078 /**079 * Adds a constructor to the class. The constructor will be public.080 * 081 * @param parameterTypes082 * the type of each parameter, or null if the constructor takes no parameters.083 * @param exceptions084 * the type of each exception, or null if the constructor throws no exceptions.085 * @param body086 * The body of the constructor.087 */088 void addConstructor(Class[] parameterTypes, Class[] exceptions, String body);089090 /**091 * Adds an implementation of toString, as a method that returns a fixed string.092 */093 void addToString(String toString);094095 /**096 * Makes the fabricated class implement the provided service interface. The interface will be added, and all methods097 * in the interface will be delegate wrappers. If toString() is not part of the delegate interface, then an098 * implementation will be supplied that returns the provided string. This method is used when creating objects that099 * proxy their behavior to some other object.100 * 101 * @param serviceInterface102 * the interface to implement103 * @param delegateExpression104 * the expression used to find the delegate on which methods should be invoked. Typically105 * a field name, such as "_delegate", or a method to invoke, such as "_service()".106 * @param toString107 * fixed value to be returned as the description of the resultant object108 */109 void proxyMethodsToDelegate(Class serviceInterface, String delegateExpression, String toString);110111 /**112 * Copies annotations from delegate class to the fabricated class.113 * 114 * @param delegateClass115 * class of the delegate116 * @since 5.2.0117 */118 void copyClassAnnotationsFromDelegate(Class delegateClass);119120 /**121 * Copies method annotations from delegate class to the methods of the fabricated class.122 * 123 * @param serviceInterface124 * service interface125 * @param delegateClass126 * class of the delegate127 * @since 5.2.0128 */129 void copyMethodAnnotationsFromDelegate(Class serviceInterface, Class delegateClass);130131 /**132 * Invoked last to create the class. This will enforce that all abstract methods have been implemented in the133 * (concrete) class.134 */135 Class createClass();136137 /**138 * Adds a public no-op method. The method will return null, false, or zero as per the return type (if not void).139 */140141 void addNoOpMethod(MethodSignature signature);142 }