KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tapestry > enhance > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc name, Class JavaDoc 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 JavaDoc addInjectedField(String JavaDoc fieldName, Class JavaDoc fieldType, Object JavaDoc 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 JavaDoc convertTypeName(String JavaDoc 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 JavaDoc name, Class JavaDoc 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 JavaDoc getAccessorMethodName(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getClassReference(Class JavaDoc 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 JavaDoc getPropertyType(String JavaDoc 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 JavaDoc interfaceClass, MethodSignature methodSignature,
146             String JavaDoc 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 JavaDoc interfaceClass);
155 }
Popular Tags