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