Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
IComponentSpecification |
|
| 1.0;1 |
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.spec; | |
16 | ||
17 | import org.apache.hivemind.Locatable; | |
18 | import org.apache.hivemind.LocationHolder; | |
19 | import org.apache.hivemind.Resource; | |
20 | import org.apache.tapestry.util.IPropertyHolder; | |
21 | ||
22 | import java.util.Collection; | |
23 | import java.util.List; | |
24 | import java.util.Set; | |
25 | ||
26 | /** | |
27 | * A specification for a component, as read from an XML specification file. | |
28 | * <p> | |
29 | * A specification consists of | |
30 | * <ul> | |
31 | * <li>An implementing class | |
32 | * <li>An optional template | |
33 | * <li>An optional description | |
34 | * <li>A set of contained components | |
35 | * <li>Bindings for the properties of each contained component | |
36 | * <li>A set of named assets | |
37 | * <li>Definitions for helper beans | |
38 | * <li>Any reserved names (used for HTML attributes) | |
39 | * </ul> | |
40 | * <p> | |
41 | * From this information, an actual component may be instantiated and | |
42 | * initialized. Instantiating a component is usually a recursive process, since | |
43 | * to initialize a container component, it is necessary to instantiate and | |
44 | * initialize its contained components as well. | |
45 | * | |
46 | * @see org.apache.tapestry.IComponent | |
47 | * @see IContainedComponent | |
48 | * @see IComponentSpecification | |
49 | * @see org.apache.tapestry.engine.IPageLoader | |
50 | * @author glongman@intelligentworks.com | |
51 | */ | |
52 | public interface IComponentSpecification extends IPropertyHolder, | |
53 | LocationHolder, Locatable, IEventListener | |
54 | { | |
55 | ||
56 | /** | |
57 | * @throws IllegalArgumentException | |
58 | * if the name already exists. | |
59 | */ | |
60 | void addAsset(String name, IAssetSpecification asset); | |
61 | ||
62 | /** | |
63 | * @throws IllegalArgumentException | |
64 | * if the id is already defined. | |
65 | */ | |
66 | void addComponent(String id, IContainedComponent component); | |
67 | ||
68 | /** | |
69 | * Adds the parameter. The parameter name and aliases are added as a | |
70 | * reserved name. The code assumes that the parameter specification will | |
71 | * <strong>not</strong> be subsequently changed. | |
72 | * | |
73 | * @throws IllegalArgumentException | |
74 | * if the name already exists. | |
75 | */ | |
76 | void addParameter(IParameterSpecification spec); | |
77 | ||
78 | /** | |
79 | * Returns true if the component is allowed to wrap other elements (static | |
80 | * HTML or other components). The default is true. | |
81 | * | |
82 | * @see #setAllowBody(boolean) | |
83 | */ | |
84 | boolean getAllowBody(); | |
85 | ||
86 | /** | |
87 | * Returns true if the component allows informal parameters (parameters not | |
88 | * formally defined). Informal parameters are generally used to create | |
89 | * additional HTML attributes for an HTML tag rendered by the component. | |
90 | * This is often used to specify JavaScript event handlers or the class of | |
91 | * the component (for Cascarding Style Sheets). | |
92 | * <p> | |
93 | * The default value is true. | |
94 | * | |
95 | * @see #setAllowInformalParameters(boolean) | |
96 | */ | |
97 | boolean getAllowInformalParameters(); | |
98 | ||
99 | /** | |
100 | * Returns the {@link IAssetSpecification}with the given name, or null if | |
101 | * no such specification exists. | |
102 | * | |
103 | * @see #addAsset(String,IAssetSpecification) | |
104 | */ | |
105 | IAssetSpecification getAsset(String name); | |
106 | ||
107 | /** | |
108 | * Returns a <code>List</code> of the String names of all assets, in | |
109 | * alphabetical order. | |
110 | */ | |
111 | List getAssetNames(); | |
112 | ||
113 | /** | |
114 | * Returns the specification of a contained component with the given id, or | |
115 | * null if no such contained component exists. | |
116 | * | |
117 | * @see #addComponent(String, IContainedComponent) | |
118 | */ | |
119 | IContainedComponent getComponent(String id); | |
120 | ||
121 | /** | |
122 | * Returns the class name to be used when instantiating the component, or | |
123 | * null if no class name was provided in the specification (in which case, a | |
124 | * system of defaults will be used to determine the class name). | |
125 | */ | |
126 | ||
127 | String getComponentClassName(); | |
128 | ||
129 | /** | |
130 | * Returns an <code>List</code> of the String names of the | |
131 | * {@link IContainedComponent}s for this component. | |
132 | * | |
133 | * @see #addComponent(String, IContainedComponent) | |
134 | */ | |
135 | List getComponentIds(); | |
136 | ||
137 | /** | |
138 | * Returns the specification of a parameter with the given name, or null if | |
139 | * no such parameter exists. | |
140 | * | |
141 | * @see #addParameter(IParameterSpecification) | |
142 | */ | |
143 | IParameterSpecification getParameter(String name); | |
144 | ||
145 | /** | |
146 | * Returns an unordered collection of {@link IParameterSpecification}, for | |
147 | * all parameters that are required. This includes only "real" parameters, | |
148 | * not aliases. | |
149 | * | |
150 | * @since 4.0 | |
151 | */ | |
152 | ||
153 | Collection getRequiredParameters(); | |
154 | ||
155 | /** | |
156 | * Returns a List of of String names of all parameters. This list is in | |
157 | * alphabetical order. | |
158 | * | |
159 | * @see #addParameter(IParameterSpecification) | |
160 | */ | |
161 | List getParameterNames(); | |
162 | ||
163 | void setAllowBody(boolean value); | |
164 | ||
165 | void setAllowInformalParameters(boolean value); | |
166 | ||
167 | void setComponentClassName(String value); | |
168 | ||
169 | /** | |
170 | * @since 1.0.4 | |
171 | * @throws IllegalArgumentException | |
172 | * if the bean already has a specification. | |
173 | */ | |
174 | void addBeanSpecification(String name, IBeanSpecification specification); | |
175 | ||
176 | /** | |
177 | * Returns the {@link IBeanSpecification}for the given name, or null if not | |
178 | * such specification exists. | |
179 | * | |
180 | * @since 1.0.4 | |
181 | */ | |
182 | IBeanSpecification getBeanSpecification(String name); | |
183 | ||
184 | /** | |
185 | * Returns an unmodifiable collection of the names of all beans. | |
186 | */ | |
187 | Collection getBeanNames(); | |
188 | ||
189 | /** | |
190 | * Adds the value as a reserved name. Reserved names are not allowed as the | |
191 | * names of informal parameters. Since the comparison is caseless, the value | |
192 | * is converted to lowercase before being stored. | |
193 | * | |
194 | * @since 1.0.5 | |
195 | */ | |
196 | void addReservedParameterName(String value); | |
197 | ||
198 | /** | |
199 | * Returns true if the value specified is in the reserved name list. The | |
200 | * comparison is caseless. All formal parameters are automatically in the | |
201 | * reserved name list, as well as any additional reserved names specified in | |
202 | * the component specification. The latter refer to HTML attributes | |
203 | * generated directly by the component. | |
204 | * | |
205 | * @since 1.0.5 | |
206 | */ | |
207 | boolean isReservedParameterName(String value); | |
208 | ||
209 | /** | |
210 | * Returns the documentation for this component. | |
211 | * | |
212 | * @since 1.0.9 | |
213 | */ | |
214 | String getDescription(); | |
215 | ||
216 | /** | |
217 | * Sets the documentation for this component. | |
218 | * | |
219 | * @since 1.0.9 | |
220 | */ | |
221 | void setDescription(String description); | |
222 | ||
223 | /** | |
224 | * Returns the XML Public Id for the specification file, or null if not | |
225 | * applicable. | |
226 | * <p> | |
227 | * This method exists as a convienience for the Spindle plugin. A previous | |
228 | * method used an arbitrary version string, the public id is more useful and | |
229 | * less ambiguous. | |
230 | * | |
231 | * @since 2.2 | |
232 | */ | |
233 | String getPublicId(); | |
234 | ||
235 | /** @since 2.2 * */ | |
236 | void setPublicId(String publicId); | |
237 | ||
238 | /** | |
239 | * Returns true if the specification is known to be a page specification and | |
240 | * not a component specification. Earlier versions of the framework did not | |
241 | * distinguish between the two, but starting in 2.2, there are seperate XML | |
242 | * entities for pages and components. Pages omit several attributes and | |
243 | * entities related to parameters, as parameters only make sense for | |
244 | * components. | |
245 | * | |
246 | * @since 2.2 | |
247 | */ | |
248 | boolean isPageSpecification(); | |
249 | ||
250 | /** @since 2.2 * */ | |
251 | void setPageSpecification(boolean pageSpecification); | |
252 | ||
253 | /** @since 3.0 * */ | |
254 | Resource getSpecificationLocation(); | |
255 | ||
256 | /** @since 3.0 * */ | |
257 | void setSpecificationLocation(Resource specificationLocation); | |
258 | ||
259 | /** | |
260 | * Adds a new property specification. The name of the property must not | |
261 | * already be defined (and must not change after being added). | |
262 | * | |
263 | * @since 3.0 | |
264 | */ | |
265 | void addPropertySpecification(IPropertySpecification spec); | |
266 | ||
267 | /** | |
268 | * Returns a sorted, immutable list of the names of all | |
269 | * {@link org.apache.tapestry.spec.IPropertySpecification}s. | |
270 | * | |
271 | * @since 3.0 | |
272 | */ | |
273 | List getPropertySpecificationNames(); | |
274 | ||
275 | /** | |
276 | * Returns the named {@link org.apache.tapestry.spec.IPropertySpecification}, | |
277 | * or null if no such specification exist. | |
278 | * | |
279 | * @since 3.0 | |
280 | * @see #addPropertySpecification(IPropertySpecification) | |
281 | */ | |
282 | IPropertySpecification getPropertySpecification(String name); | |
283 | ||
284 | /** | |
285 | * Adds a {@link InjectSpecification}. | |
286 | * | |
287 | * @since 4.0 | |
288 | */ | |
289 | ||
290 | void addInjectSpecification(InjectSpecification spec); | |
291 | ||
292 | /** | |
293 | * Returns the list of {@link InjectSpecification}. Will return an empty | |
294 | * list if no specifications have been added. | |
295 | * | |
296 | * @since 4.0 | |
297 | */ | |
298 | ||
299 | List getInjectSpecifications(); | |
300 | ||
301 | /** | |
302 | * Returns true if the component is deprecated. Deprecated components | |
303 | * generate a warning when used. | |
304 | * | |
305 | * @since 4.0 | |
306 | */ | |
307 | ||
308 | boolean isDeprecated(); | |
309 | ||
310 | /** | |
311 | * @since 4.0 | |
312 | */ | |
313 | ||
314 | void setDeprecated(boolean deprecated); | |
315 | ||
316 | /** | |
317 | * Returns a Set of Strings; the reserved parameter names for the component. | |
318 | * This combines explicit reserved names with formal parameter names. Each | |
319 | * parameter name in the Set will be all lower case (to facilitate a | |
320 | * caseless comparison). | |
321 | * | |
322 | * @returns an unmodifiable set (of String), possibly empty | |
323 | * @since 4.0 | |
324 | */ | |
325 | ||
326 | Set getReservedParameterNames(); | |
327 | } |