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
015package org.apache.tapestry.spec;
016
017import java.util.Collection;
018import java.util.List;
019import java.util.Set;
020
021import org.apache.hivemind.Locatable;
022import org.apache.hivemind.LocationHolder;
023import org.apache.hivemind.Resource;
024import 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 */
051public 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}