KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tapestry > spec > IComponentSpecification


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 JavaDoc;
18 import java.util.List JavaDoc;
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 JavaDoc name, IAssetSpecification asset);
57
58     /**
59      * @throws IllegalArgumentException
60      * if the id is already defined.
61      */

62     public void addComponent(String JavaDoc 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 JavaDoc name);
100
101     /**
102      * Returns a <code>List</code> of the String names of all assets, in alphabetical order
103      */

104     public List JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getParameterNames();
153
154     public void setAllowBody(boolean value);
155
156     public void setAllowInformalParameters(boolean value);
157
158     public void setComponentClassName(String JavaDoc 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 JavaDoc 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 JavaDoc name);
174
175     /**
176      * Returns an unmodifiable collection of the names of all beans.
177      */

178     public Collection JavaDoc 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 JavaDoc 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 JavaDoc value);
198
199     /**
200      * Returns the documentation for this component.
201      *
202      * @since 1.0.9
203      */

204     public String JavaDoc getDescription();
205
206     /**
207      * Sets the documentation for this component.
208      *
209      * @since 1.0.9
210      */

211     public void setDescription(String JavaDoc 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 JavaDoc getPublicId();
222
223     /** @since 2.2 * */
224     public void setPublicId(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 }
Popular Tags