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 | } |