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