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