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    }