001// Copyright 2004, 2005 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.hivemind.service;
016
017/**
018 * Used when fabricating a new class.  Represents a wrapper around
019 * the Javassist library.
020 * 
021 * <p>
022 * The core concept of Javassist is how method bodies (as well as constructor bodies, etc.)
023 * are specified ... as a very Java-like scripting language.  The 
024 * {@link org.apache.hivemind.service.BodyBuilder} class is <em>very</em> useful for assembling
025 * this method bodies.  Details are available at the
026 * <a href="http://jboss.org/products/javassist">Javassist home page</a>.
027 * 
028 * <p>
029 * Method bodies look largely like Java. References to java classes must be fully qualified.
030 * Several special variables are used:
031 * <ul>
032 * <li><code>$0</code> first parameter, equivalent to <code>this</code> in Java code (and can't
033 * be used when creating a static method)
034 * <li><code>$1, $2, ...</code> actual parameters to the method
035 * <li><code>$args</code> all the parameters as an <code>Object[]</code>
036 * <li><code>$r</code> the return type of the method, typically used as <code>return ($r) ...</code>.
037 * <code>$r</code> is valid with method that return <code>void</code>. This also handles conversions
038 * between wrapper types and primitive types.
039 * <li><code>$w</code> conversion from primitive type to wrapper type, used as <code>($w) foo()</code> where
040 * <code>foo()</code> returns a primitive type and a wrapper type is needed
041 * <li>
042 * </ul>
043 *
044 * @author Howard Lewis Ship
045 */
046public interface ClassFab
047{
048    /**
049     * Adds the specified interface as an interface implemented by this class.
050     */
051    public void addInterface(Class interfaceClass);
052
053    /**
054     * Adds a new field with the given name and type.  The field is
055     * added as a private field.
056     */
057
058    public void addField(String name, Class type);
059
060    /**
061     * Convenience method for checking whether the fabricated class already contains
062     * a method.
063     * @param signature the signature
064     * @return whether or not the fabricated class already contains the method
065     */
066    public boolean containsMethod( MethodSignature signature );
067    
068    /**
069     * Adds a method.  The method is a public instance method.
070     * @return a method fabricator, used to add catch handlers.
071     * @param modifiers Modifiers for the method (see {@link java.lang.reflect.Modifier}).
072     * @param signature defines the name, return type, parameters and exceptions thrown
073     * @param body The body of the method.
074     * @throws ApplicationRuntimeException if a method with that signature has already
075     * been added, or if there is a Javassist compilation error
076     */
077
078    public MethodFab addMethod(int modifiers, MethodSignature signature, String body);
079
080    /**
081     * Returns a previous defined method so that it can be further enhanced
082     * (perhaps by adding additional catches, etc.).
083     * 
084     * @param signature the signature of the method previously added
085     * @return the MethodFab for that method, or null if the method has not been added yet
086     */
087
088    public MethodFab getMethodFab(MethodSignature signature);
089
090    /**
091     * Adds a constructor to the class.  The constructor will be public.
092     * @param parameterTypes the type of each parameter, or null if the constructor takes no parameters.
093     * @param exceptions the type of each exception, or null if the constructor throws no exceptions.
094     * @param body The body of the constructor.
095     */
096    public void addConstructor(Class[] parameterTypes, Class[] exceptions, String body);
097
098    /**
099     * Invoked last to create the class.  This will enforce that
100     * all abstract methods have been implemented in the (concrete) class.
101     */
102    public Class createClass();
103}