EnhancementOperation


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.tapestry.enhance;
16  
17  import java.util.List  ;
18  
19  import org.apache.hivemind.service.MethodSignature;
20  
21  /**
22   * A process object representing enhancements to a component class. The operation is passed to
23   * {@link org.apache.tapestry.enhance.EnhancementWorker}objects that perform enhancements.
24   * 
25   * @author Howard M. Lewis Ship
26   * @since 4.0
27   */
28  public interface EnhancementOperation
29  {
30      /**
31       * Claims a property. Most enhancements are concerned with adding properties. Some enhancement
32       * workers exist to fill in defaults, and they need to know what properties have already been
33       * spoken for by eariler enhancement works.
34       * 
35       * @throws org.apache.hivemind.ApplicationRuntimeException
36       *             if the property was previously claimed
37       */
38  
39      public void claimProperty(String   propertyName);
40  
41      /**
42       * Returns a list of the names of existing properties that are not claimed and which have
43       * abstract accessor methods.
44       */
45  
46      public List   findUnclaimedAbstractProperties();
47  
48      /**
49       * Adds a field to the enhanced class; the field will be private and use the provided name and
50       * type.
51       */
52  
53      public void addField(String   name, Class   type);
54  
55      /**
56       * Adds a field containing an initial value, which is injected into the class via its fabricated
57       * constructor. This method may be called multiple times with the same value and will return the
58       * same variable name (an identity map is kept internally).
59       * 
60       * @param fieldName
61       *            The default name for the field, used if a new field (and contructor argument) is
62       *            being created. Only used if a field for the value doesn't exist.
63       * @param fieldType
64       *            The type of the field to be created.
65       * @param value
66       *            the value to be referenced, which may not be null
67       * @return the name of the field containing the value. This may or may not match fieldName. The
68       *         provided fieldName may be modified to prevent naming conflicts.
69       */
70  
71      public String   addInjectedField(String   fieldName, Class   fieldType, Object   value);
72  
73      /**
74       * Converts a type name (an object class name, a primtive name, or an array) into the
75       * corresponding Class object.
76       */
77  
78      public Class   convertTypeName(String   type);
79  
80      /**
81       * Confirms that the named property either doesn't exist (in the component base class), or that
82       * the type of the property exactly matches the indicated type.
83       */
84  
85      public void validateProperty(String   name, Class   expectedType);
86  
87      /**
88       * Returns the name of the accessor method for the given property (if it exists in the component
89       * base class), or fabricates a new name if it does not.
90       */
91  
92      public String   getAccessorMethodName(String   propertyName);
93  
94      /**
95       * Adds a method to the enhanced class.
96       * 
97       * @param modifier
98       *            as defined by {@link java.lang.reflect.Modifier}, typically
99       *            {@link java.lang.reflect.Modifier#PUBLIC}
100      * @param sig
101      *            the method signature (defining name, return type, etc.)
102      * @param methodBody
103      *            a Javassist code snippet for the method body
104      */
105     public void addMethod(int modifier, MethodSignature sig, String   methodBody);
106 
107     /**
108      * Returns the base component class, as defined in the specification (or defaulted). An enhaced
109      * subclass of the component class will usually be created.
110      */
111     public Class   getBaseClass();
112 
113     /**
114      * Returns a reference to a particular class. This will, effectively, by the name of a private
115      * field.
116      */
117 
118     public String   getClassReference(Class   clazz);
119 
120     /**
121      * Returns the type of an existing property of the base component class. If the property does
122      * not exist, then returns null.
123      */
124 
125     public Class   getPropertyType(String   name);
126 
127     /**
128      * Allows for a kind of distributed construction of a particular method, within a particular
129      * interface. Code can be appended to the method's implementation throughout the course of the
130      * enhancement operation. When the enhanced class is finialized, the method is added with
131      * whatever contents are in its body. If the base class implements the method, then the method
132      * body will include an initial call to that implementation.
133      * <p>
134      * At this time, this works best for void methods (since there isn't an easy way to ensure code
135      * would be inserted before a final return statement).
136      * 
137      * @param interfaceClass
138      *            the interface containing the method. If the base class does not implement the
139      *            interface, then the enhanced class will have the interface added.
140      * @param methodSignature
141      *            the signature of the method to be added.
142      * @param code
143      *            the Javassist markup to be added to the body of the method.
144      */
145     public void extendMethodImplementation(Class   interfaceClass, MethodSignature methodSignature,
146             String   code);
147 
148     /**
149      * Returns true if the class implements the specified interface. Checks the base class (as
150      * identified in the specification), but <em>also</em> accounts for any additional interfaces
151      * that may be added by {@link #extendMethodImplementation(Class, MethodSignature, String)}.
152      */
153 
154     public boolean implementsInterface(Class   interfaceClass);
155 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags