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, 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,
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    }