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 java.util.Collection; |
|
18 | import java.util.List; |
|
19 | import java.util.Set; |
|
20 | ||
21 | import org.apache.hivemind.Locatable; |
|
22 | import org.apache.hivemind.LocationHolder; |
|
23 | import org.apache.hivemind.Resource; |
|
24 | import org.apache.tapestry.util.IPropertyHolder; |
|
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, |
|
175 | IBeanSpecification specification); |
|
176 | ||
177 | /** |
|
178 | * Returns the {@link IBeanSpecification}for the given name, or null if not |
|
179 | * such specification exists. |
|
180 | * |
|
181 | * @since 1.0.4 |
|
182 | */ |
|
183 | IBeanSpecification getBeanSpecification(String name); |
|
184 | ||
185 | /** |
|
186 | * Returns an unmodifiable collection of the names of all beans. |
|
187 | */ |
|
188 | Collection getBeanNames(); |
|
189 | ||
190 | /** |
|
191 | * Adds the value as a reserved name. Reserved names are not allowed as the |
|
192 | * names of informal parameters. Since the comparison is caseless, the value |
|
193 | * is converted to lowercase before being stored. |
|
194 | * |
|
195 | * @since 1.0.5 |
|
196 | */ |
|
197 | void addReservedParameterName(String value); |
|
198 | ||
199 | /** |
|
200 | * Returns true if the value specified is in the reserved name list. The |
|
201 | * comparison is caseless. All formal parameters are automatically in the |
|
202 | * reserved name list, as well as any additional reserved names specified in |
|
203 | * the component specification. The latter refer to HTML attributes |
|
204 | * generated directly by the component. |
|
205 | * |
|
206 | * @since 1.0.5 |
|
207 | */ |
|
208 | boolean isReservedParameterName(String value); |
|
209 | ||
210 | /** |
|
211 | * Returns the documentation for this component. |
|
212 | * |
|
213 | * @since 1.0.9 |
|
214 | */ |
|
215 | String getDescription(); |
|
216 | ||
217 | /** |
|
218 | * Sets the documentation for this component. |
|
219 | * |
|
220 | * @since 1.0.9 |
|
221 | */ |
|
222 | void setDescription(String description); |
|
223 | ||
224 | /** |
|
225 | * Returns the XML Public Id for the specification file, or null if not |
|
226 | * applicable. |
|
227 | * <p> |
|
228 | * This method exists as a convienience for the Spindle plugin. A previous |
|
229 | * method used an arbitrary version string, the public id is more useful and |
|
230 | * less ambiguous. |
|
231 | * |
|
232 | * @since 2.2 |
|
233 | */ |
|
234 | String getPublicId(); |
|
235 | ||
236 | /** @since 2.2 * */ |
|
237 | void setPublicId(String publicId); |
|
238 | ||
239 | /** |
|
240 | * Returns true if the specification is known to be a page specification and |
|
241 | * not a component specification. Earlier versions of the framework did not |
|
242 | * distinguish between the two, but starting in 2.2, there are seperate XML |
|
243 | * entities for pages and components. Pages omit several attributes and |
|
244 | * entities related to parameters, as parameters only make sense for |
|
245 | * components. |
|
246 | * |
|
247 | * @since 2.2 |
|
248 | */ |
|
249 | boolean isPageSpecification(); |
|
250 | ||
251 | /** @since 2.2 * */ |
|
252 | void setPageSpecification(boolean pageSpecification); |
|
253 | ||
254 | /** @since 3.0 * */ |
|
255 | Resource getSpecificationLocation(); |
|
256 | ||
257 | /** @since 3.0 * */ |
|
258 | void setSpecificationLocation(Resource specificationLocation); |
|
259 | ||
260 | /** |
|
261 | * Adds a new property specification. The name of the property must not |
|
262 | * already be defined (and must not change after being added). |
|
263 | * |
|
264 | * @since 3.0 |
|
265 | */ |
|
266 | void addPropertySpecification(IPropertySpecification spec); |
|
267 | ||
268 | /** |
|
269 | * Returns a sorted, immutable list of the names of all |
|
270 | * {@link org.apache.tapestry.spec.IPropertySpecification}s. |
|
271 | * |
|
272 | * @since 3.0 |
|
273 | */ |
|
274 | List getPropertySpecificationNames(); |
|
275 | ||
276 | /** |
|
277 | * Returns the named {@link org.apache.tapestry.spec.IPropertySpecification}, |
|
278 | * or null if no such specification exist. |
|
279 | * |
|
280 | * @since 3.0 |
|
281 | * @see #addPropertySpecification(IPropertySpecification) |
|
282 | */ |
|
283 | IPropertySpecification getPropertySpecification(String name); |
|
284 | ||
285 | /** |
|
286 | * Adds a {@link InjectSpecification}. |
|
287 | * |
|
288 | * @since 4.0 |
|
289 | */ |
|
290 | ||
291 | void addInjectSpecification(InjectSpecification spec); |
|
292 | ||
293 | /** |
|
294 | * Returns the list of {@link InjectSpecification}. Will return an empty |
|
295 | * list if no specifications have been added. |
|
296 | * |
|
297 | * @since 4.0 |
|
298 | */ |
|
299 | ||
300 | List getInjectSpecifications(); |
|
301 | ||
302 | /** |
|
303 | * Returns true if the component is deprecated. Deprecated components |
|
304 | * generate a warning when used. |
|
305 | * |
|
306 | * @since 4.0 |
|
307 | */ |
|
308 | ||
309 | boolean isDeprecated(); |
|
310 | ||
311 | /** |
|
312 | * @since 4.0 |
|
313 | */ |
|
314 | ||
315 | void setDeprecated(boolean deprecated); |
|
316 | ||
317 | /** |
|
318 | * Returns a Set of Strings; the reserved parameter names for the component. |
|
319 | * This combines explicit reserved names with formal parameter names. Each |
|
320 | * parameter name in the Set will be all lower case (to facilitate a |
|
321 | * caseless comparison). |
|
322 | * |
|
323 | * @returns an unmodifiable set (of String), possibly empty |
|
324 | * @since 4.0 |
|
325 | */ |
|
326 | ||
327 | Set getReservedParameterNames(); |
|
328 | } |