IComponentSpecification


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.tapestry.spec;
16  
17  import java.util.Collection  ;
18  import java.util.List  ;
19  
20  import org.apache.hivemind.Locatable;
21  import org.apache.hivemind.LocationHolder;
22  import org.apache.hivemind.Resource;
23  import org.apache.tapestry.util.IPropertyHolder;
24  
25  /**
26   * A specification for a component, as read from an XML specification file.
27   * <p>
28   * A specification consists of
29   * <ul>
30   * <li>An implementing class
31   * <li>An optional template
32   * <li>An optional description
33   * <li>A set of contained components
34   * <li>Bindings for the properties of each contained component
35   * <li>A set of named assets
36   * <li>Definitions for helper beans
37   * <li>Any reserved names (used for HTML attributes)
38   * </ul>
39   * <p>
40   * From this information, an actual component may be instantiated and initialized. Instantiating a
41   * component is usually a recursive process, since to initialize a container component, it is
42   * necessary to instantiate and initialize its contained components as well.
43   * 
44   * @see org.apache.tapestry.IComponent
45   * @see IContainedComponent
46   * @see IComponentSpecification
47   * @see org.apache.tapestry.engine.IPageLoader
48   * @author glongman@intelligentworks.com
49   */
50  public interface IComponentSpecification extends IPropertyHolder, LocationHolder, Locatable
51  {
52      /**
53       * @throws IllegalArgumentException
54       *             if the name already exists.
55       */
56      public void addAsset(String   name, IAssetSpecification asset);
57  
58      /**
59       * @throws IllegalArgumentException
60       *             if the id is already defined.
61       */
62      public void addComponent(String   id, IContainedComponent component);
63  
64      /**
65       * Adds the parameter. The parameter name and aliases are added as a reserved name. The code
66       * assumes that the parameter specification will <strong>not</strong> be subsequently changed.
67       * 
68       * @throws IllegalArgumentException
69       *             if the name already exists.
70       */
71      public void addParameter(IParameterSpecification spec);
72  
73      /**
74       * Returns true if the component is allowed to wrap other elements (static HTML or other
75       * components). The default is true.
76       * 
77       * @see #setAllowBody(boolean)
78       */
79      public boolean getAllowBody();
80  
81      /**
82       * Returns true if the component allows informal parameters (parameters not formally defined).
83       * Informal parameters are generally used to create additional HTML attributes for an HTML tag
84       * rendered by the component. This is often used to specify JavaScript event handlers or the
85       * class of the component (for Cascarding Style Sheets).
86       * <p>
87       * The default value is true.
88       * 
89       * @see #setAllowInformalParameters(boolean)
90       */
91      public boolean getAllowInformalParameters();
92  
93      /**
94       * Returns the {@link IAssetSpecification}with the given name, or null if no such specification
95       * exists.
96       * 
97       * @see #addAsset(String,IAssetSpecification)
98       */
99      public IAssetSpecification getAsset(String   name);
100 
101     /**
102      * Returns a <code>List</code> of the String names of all assets, in alphabetical order
103      */
104     public List   getAssetNames();
105 
106     /**
107      * Returns the specification of a contained component with the given id, or null if no such
108      * contained component exists.
109      * 
110      * @see #addComponent(String, IContainedComponent)
111      */
112     public IContainedComponent getComponent(String   id);
113 
114     /**
115      * Returns the class name to be used when instantiating the component, or null if no class name
116      * was provided in the specification (in which case, a system of defaults will be used to
117      * determine the class name).
118      */
119 
120     public String   getComponentClassName();
121 
122     /**
123      * Returns an <code>List</code> of the String names of the {@link IContainedComponent}s for
124      * this component.
125      * 
126      * @see #addComponent(String, IContainedComponent)
127      */
128     public List   getComponentIds();
129 
130     /**
131      * Returns the specification of a parameter with the given name, or null if no such parameter
132      * exists.
133      * 
134      * @see #addParameter(String, IParameterSpecification)
135      */
136     public IParameterSpecification getParameter(String   name);
137 
138     /**
139      * Returns an unordered collection of {@link IParameterSpecification}, for all parameters that
140      * are required. This includes only "real" parameters, not aliases.
141      * 
142      * @since 4.0
143      */
144 
145     public Collection   getRequiredParameters();
146 
147     /**
148      * Returns a List of of String names of all parameters. This list is in alphabetical order.
149      * 
150      * @see #addParameter(String, IParameterSpecification)
151      */
152     public List   getParameterNames();
153 
154     public void setAllowBody(boolean value);
155 
156     public void setAllowInformalParameters(boolean value);
157 
158     public void setComponentClassName(String   value);
159 
160     /**
161      * @since 1.0.4
162      * @throws IllegalArgumentException
163      *             if the bean already has a specification.
164      */
165     public void addBeanSpecification(String   name, IBeanSpecification specification);
166 
167     /**
168      * Returns the {@link IBeanSpecification}for the given name, or null if not such specification
169      * exists.
170      * 
171      * @since 1.0.4
172      */
173     public IBeanSpecification getBeanSpecification(String   name);
174 
175     /**
176      * Returns an unmodifiable collection of the names of all beans.
177      */
178     public Collection   getBeanNames();
179 
180     /**
181      * Adds the value as a reserved name. Reserved names are not allowed as the names of informal
182      * parameters. Since the comparison is caseless, the value is converted to lowercase before
183      * being stored.
184      * 
185      * @since 1.0.5
186      */
187     public void addReservedParameterName(String   value);
188 
189     /**
190      * Returns true if the value specified is in the reserved name list. The comparison is caseless.
191      * All formal parameters are automatically in the reserved name list, as well as any additional
192      * reserved names specified in the component specification. The latter refer to HTML attributes
193      * generated directly by the component.
194      * 
195      * @since 1.0.5
196      */
197     public boolean isReservedParameterName(String   value);
198 
199     /**
200      * Returns the documentation for this component.
201      * 
202      * @since 1.0.9
203      */
204     public String   getDescription();
205 
206     /**
207      * Sets the documentation for this component.
208      * 
209      * @since 1.0.9
210      */
211     public void setDescription(String   description);
212 
213     /**
214      * Returns the XML Public Id for the specification file, or null if not applicable.
215      * <p>
216      * This method exists as a convienience for the Spindle plugin. A previous method used an
217      * arbitrary version string, the public id is more useful and less ambiguous.
218      * 
219      * @since 2.2
220      */
221     public String   getPublicId();
222 
223     /** @since 2.2 * */
224     public void setPublicId(String   publicId);
225 
226     /**
227      * Returns true if the specification is known to be a page specification and not a component
228      * specification. Earlier versions of the framework did not distinguish between the two, but
229      * starting in 2.2, there are seperate XML entities for pages and components. Pages omit several
230      * attributes and entities related to parameters, as parameters only make sense for components.
231      * 
232      * @since 2.2
233      */
234     public boolean isPageSpecification();
235 
236     /** @since 2.2 * */
237     public void setPageSpecification(boolean pageSpecification);
238 
239     /** @since 3.0 * */
240     public Resource getSpecificationLocation();
241 
242     /** @since 3.0 * */
243     public void setSpecificationLocation(Resource specificationLocation);
244 
245     /**
246      * Adds a new property specification. The name of the property must not already be defined (and
247      * must not change after being added).
248      * 
249      * @since 3.0
250      */
251     public void addPropertySpecification(IPropertySpecification spec);
252 
253     /**
254      * Returns a sorted, immutable list of the names of all
255      * {@link org.apache.tapestry.spec.IPropertySpecification}s.
256      * 
257      * @since 3.0
258      */
259     public List   getPropertySpecificationNames();
260 
261     /**
262      * Returns the named {@link org.apache.tapestry.spec.IPropertySpecification}, or null if no
263      * such specification exist.
264      * 
265      * @since 3.0
266      * @see #addPropertySpecification(IPropertySpecification)
267      */
268     public IPropertySpecification getPropertySpecification(String   name);
269 
270     /**
271      * Adds a {@link InjectSpecification}.
272      * 
273      * @since 4.0
274      */
275 
276     public void addInjectSpecification(InjectSpecification spec);
277 
278     /**
279      * Returns the list of {@link InjectSpecification}. Will return an empty list if no
280      * specifications have been added.
281      * 
282      * @since 4.0
283      */
284 
285     public List   getInjectSpecifications();
286 
287     /**
288      * Returns true if the component is deprecated. Deprecated components generate a warning when
289      * used.
290      * 
291      * @since 4.0
292      */
293 
294     public boolean isDeprecated();
295 
296     /**
297      * @since 4.0
298      */
299 
300     public void setDeprecated(boolean deprecated);
301 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags