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 initialized. Instantiating a
042 * component is usually a recursive process, since to initialize a container component, it is
043 * necessary to instantiate and initialize its contained components as well.
044 *
045 * @see org.apache.tapestry.IComponent
046 * @see IContainedComponent
047 * @see IComponentSpecification
048 * @see org.apache.tapestry.engine.IPageLoader
049 * @author glongman@intelligentworks.com
050 */
051 public interface IComponentSpecification extends IPropertyHolder, LocationHolder, Locatable
052 {
053 /**
054 * @throws IllegalArgumentException
055 * if the name already exists.
056 */
057 public void addAsset(String name, IAssetSpecification asset);
058
059 /**
060 * @throws IllegalArgumentException
061 * if the id is already defined.
062 */
063 public void addComponent(String id, IContainedComponent component);
064
065 /**
066 * Adds the parameter. The parameter name and aliases are added as a reserved name. The code
067 * assumes that the parameter specification will <strong>not</strong> be subsequently changed.
068 *
069 * @throws IllegalArgumentException
070 * if the name already exists.
071 */
072 public void addParameter(IParameterSpecification spec);
073
074 /**
075 * Returns true if the component is allowed to wrap other elements (static HTML or other
076 * components). The default is true.
077 *
078 * @see #setAllowBody(boolean)
079 */
080 public boolean getAllowBody();
081
082 /**
083 * Returns true if the component allows informal parameters (parameters not formally defined).
084 * Informal parameters are generally used to create additional HTML attributes for an HTML tag
085 * rendered by the component. This is often used to specify JavaScript event handlers or the
086 * class of the component (for Cascarding Style Sheets).
087 * <p>
088 * The default value is true.
089 *
090 * @see #setAllowInformalParameters(boolean)
091 */
092 public boolean getAllowInformalParameters();
093
094 /**
095 * Returns the {@link IAssetSpecification}with the given name, or null if no such specification
096 * exists.
097 *
098 * @see #addAsset(String,IAssetSpecification)
099 */
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 }