Clover coverage report - Code Coverage for tapestry release 4.0-beta-12
Coverage timestamp: Sun Oct 30 2005 16:22:01 EST
file stats: LOC: 314   Methods: 0
NCLOC: 47   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
IComponentSpecification.java - - - -
coverage
 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    import java.util.Set;
 20   
 21    import org.apache.hivemind.Locatable;
 22    import org.apache.hivemind.LocationHolder;
 23    import org.apache.hivemind.Resource;
 24    import org.apache.tapestry.util.IPropertyHolder;
 25   
 26    /**
 27    * A specification for a component, as read from an XML specification file.
 28    * <p>
 29    * A specification consists of
 30    * <ul>
 31    * <li>An implementing class
 32    * <li>An optional template
 33    * <li>An optional description
 34    * <li>A set of contained components
 35    * <li>Bindings for the properties of each contained component
 36    * <li>A set of named assets
 37    * <li>Definitions for helper beans
 38    * <li>Any reserved names (used for HTML attributes)
 39    * </ul>
 40    * <p>
 41    * From this information, an actual component may be instantiated and initialized. Instantiating a
 42    * component is usually a recursive process, since to initialize a container component, it is
 43    * necessary to instantiate and initialize its contained components as well.
 44    *
 45    * @see org.apache.tapestry.IComponent
 46    * @see IContainedComponent
 47    * @see IComponentSpecification
 48    * @see org.apache.tapestry.engine.IPageLoader
 49    * @author glongman@intelligentworks.com
 50    */
 51    public interface IComponentSpecification extends IPropertyHolder, LocationHolder, Locatable
 52    {
 53    /**
 54    * @throws IllegalArgumentException
 55    * if the name already exists.
 56    */
 57    public void addAsset(String name, IAssetSpecification asset);
 58   
 59    /**
 60    * @throws IllegalArgumentException
 61    * if the id is already defined.
 62    */
 63    public void addComponent(String id, IContainedComponent component);
 64   
 65    /**
 66    * Adds the parameter. The parameter name and aliases are added as a reserved name. The code
 67    * assumes that the parameter specification will <strong>not</strong> be subsequently changed.
 68    *
 69    * @throws IllegalArgumentException
 70    * if the name already exists.
 71    */
 72    public void addParameter(IParameterSpecification spec);
 73   
 74    /**
 75    * Returns true if the component is allowed to wrap other elements (static HTML or other
 76    * components). The default is true.
 77    *
 78    * @see #setAllowBody(boolean)
 79    */
 80    public boolean getAllowBody();
 81   
 82    /**
 83    * Returns true if the component allows informal parameters (parameters not formally defined).
 84    * Informal parameters are generally used to create additional HTML attributes for an HTML tag
 85    * rendered by the component. This is often used to specify JavaScript event handlers or the
 86    * class of the component (for Cascarding Style Sheets).
 87    * <p>
 88    * The default value is true.
 89    *
 90    * @see #setAllowInformalParameters(boolean)
 91    */
 92    public boolean getAllowInformalParameters();
 93   
 94    /**
 95    * Returns the {@link IAssetSpecification}with the given name, or null if no such specification
 96    * exists.
 97    *
 98    * @see #addAsset(String,IAssetSpecification)
 99    */
 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    }