001 // Copyright 2004, 2005 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry.spec;
016
017 import java.util.Collection;
018 import java.util.List;
019 import java.util.Set;
020
021 import org.apache.hivemind.Locatable;
022 import org.apache.hivemind.LocationHolder;
023 import org.apache.hivemind.Resource;
024 import org.apache.tapestry.util.IPropertyHolder;
025
026 /**
027 * A specification for a component, as read from an XML specification file.
028 * <p>
029 * A specification consists of
030 * <ul>
031 * <li>An implementing class
032 * <li>An optional template
033 * <li>An optional description
034 * <li>A set of contained components
035 * <li>Bindings for the properties of each contained component
036 * <li>A set of named assets
037 * <li>Definitions for helper beans
038 * <li>Any reserved names (used for HTML attributes)
039 * </ul>
040 * <p>
041 * From this information, an actual component may be instantiated and
042 * initialized. Instantiating a component is usually a recursive process, since
043 * to initialize a container component, it is necessary to instantiate and
044 * initialize its contained components as well.
045 *
046 * @see org.apache.tapestry.IComponent
047 * @see IContainedComponent
048 * @see IComponentSpecification
049 * @see org.apache.tapestry.engine.IPageLoader
050 * @author glongman@intelligentworks.com
051 */
052 public interface IComponentSpecification extends IPropertyHolder,
053 LocationHolder, Locatable
054 {
055
056 /**
057 * @throws IllegalArgumentException
058 * if the name already exists.
059 */
060 void addAsset(String name, IAssetSpecification asset);
061
062 /**
063 * @throws IllegalArgumentException
064 * if the id is already defined.
065 */
066 void addComponent(String id, IContainedComponent component);
067
068 /**
069 * Adds the parameter. The parameter name and aliases are added as a
070 * reserved name. The code assumes that the parameter specification will
071 * <strong>not</strong> be subsequently changed.
072 *
073 * @throws IllegalArgumentException
074 * if the name already exists.
075 */
076 void addParameter(IParameterSpecification spec);
077
078 /**
079 * Returns true if the component is allowed to wrap other elements (static
080 * HTML or other components). The default is true.
081 *
082 * @see #setAllowBody(boolean)
083 */
084 boolean getAllowBody();
085
086 /**
087 * Returns true if the component allows informal parameters (parameters not
088 * formally defined). Informal parameters are generally used to create
089 * additional HTML attributes for an HTML tag rendered by the component.
090 * This is often used to specify JavaScript event handlers or the class of
091 * the component (for Cascarding Style Sheets).
092 * <p>
093 * The default value is true.
094 *
095 * @see #setAllowInformalParameters(boolean)
096 */
097 boolean getAllowInformalParameters();
098
099 /**
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(String, 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(String, 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
329 }