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