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