Coverage Report - org.apache.tapestry.spec.IComponentSpecification
 
Classes in this File Line Coverage Branch Coverage Complexity
IComponentSpecification
N/A
N/A
1
 
 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 org.apache.hivemind.Locatable;
 18  
 import org.apache.hivemind.LocationHolder;
 19  
 import org.apache.hivemind.Resource;
 20  
 import org.apache.tapestry.util.IPropertyHolder;
 21  
 
 22  
 import java.util.Collection;
 23  
 import java.util.List;
 24  
 import java.util.Set;
 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
 42  
  * initialized. Instantiating a component is usually a recursive process, since
 43  
  * to initialize a container component, it is necessary to instantiate and
 44  
  * initialize its contained components as well.
 45  
  * 
 46  
  * @see org.apache.tapestry.IComponent
 47  
  * @see IContainedComponent
 48  
  * @see IComponentSpecification
 49  
  * @see org.apache.tapestry.engine.IPageLoader
 50  
  * @author glongman@intelligentworks.com
 51  
  */
 52  
 public interface IComponentSpecification extends IPropertyHolder,
 53  
         LocationHolder, Locatable, IEventListener
 54  
 {
 55  
 
 56  
     /**
 57  
      * @throws IllegalArgumentException
 58  
      *             if the name already exists.
 59  
      */
 60  
     void addAsset(String name, IAssetSpecification asset);
 61  
 
 62  
     /**
 63  
      * @throws IllegalArgumentException
 64  
      *             if the id is already defined.
 65  
      */
 66  
     void addComponent(String id, IContainedComponent component);
 67  
 
 68  
     /**
 69  
      * Adds the parameter. The parameter name and aliases are added as a
 70  
      * reserved name. The code assumes that the parameter specification will
 71  
      * <strong>not</strong> be subsequently changed.
 72  
      * 
 73  
      * @throws IllegalArgumentException
 74  
      *             if the name already exists.
 75  
      */
 76  
     void addParameter(IParameterSpecification spec);
 77  
 
 78  
     /**
 79  
      * Returns true if the component is allowed to wrap other elements (static
 80  
      * HTML or other components). The default is true.
 81  
      * 
 82  
      * @see #setAllowBody(boolean)
 83  
      */
 84  
     boolean getAllowBody();
 85  
 
 86  
     /**
 87  
      * Returns true if the component allows informal parameters (parameters not
 88  
      * formally defined). Informal parameters are generally used to create
 89  
      * additional HTML attributes for an HTML tag rendered by the component.
 90  
      * This is often used to specify JavaScript event handlers or the class of
 91  
      * the component (for Cascarding Style Sheets).
 92  
      * <p>
 93  
      * The default value is true.
 94  
      * 
 95  
      * @see #setAllowInformalParameters(boolean)
 96  
      */
 97  
     boolean getAllowInformalParameters();
 98  
 
 99  
     /**
 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, IBeanSpecification specification);
 175  
 
 176  
     /**
 177  
      * Returns the {@link IBeanSpecification}for the given name, or null if not
 178  
      * such specification exists.
 179  
      * 
 180  
      * @since 1.0.4
 181  
      */
 182  
     IBeanSpecification getBeanSpecification(String name);
 183  
 
 184  
     /**
 185  
      * Returns an unmodifiable collection of the names of all beans.
 186  
      */
 187  
     Collection getBeanNames();
 188  
 
 189  
     /**
 190  
      * Adds the value as a reserved name. Reserved names are not allowed as the
 191  
      * names of informal parameters. Since the comparison is caseless, the value
 192  
      * is converted to lowercase before being stored.
 193  
      * 
 194  
      * @since 1.0.5
 195  
      */
 196  
     void addReservedParameterName(String value);
 197  
 
 198  
     /**
 199  
      * Returns true if the value specified is in the reserved name list. The
 200  
      * comparison is caseless. All formal parameters are automatically in the
 201  
      * reserved name list, as well as any additional reserved names specified in
 202  
      * the component specification. The latter refer to HTML attributes
 203  
      * generated directly by the component.
 204  
      * 
 205  
      * @since 1.0.5
 206  
      */
 207  
     boolean isReservedParameterName(String value);
 208  
 
 209  
     /**
 210  
      * Returns the documentation for this component.
 211  
      * 
 212  
      * @since 1.0.9
 213  
      */
 214  
     String getDescription();
 215  
 
 216  
     /**
 217  
      * Sets the documentation for this component.
 218  
      * 
 219  
      * @since 1.0.9
 220  
      */
 221  
     void setDescription(String description);
 222  
 
 223  
     /**
 224  
      * Returns the XML Public Id for the specification file, or null if not
 225  
      * applicable.
 226  
      * <p>
 227  
      * This method exists as a convienience for the Spindle plugin. A previous
 228  
      * method used an arbitrary version string, the public id is more useful and
 229  
      * less ambiguous.
 230  
      * 
 231  
      * @since 2.2
 232  
      */
 233  
     String getPublicId();
 234  
 
 235  
     /** @since 2.2 * */
 236  
     void setPublicId(String publicId);
 237  
 
 238  
     /**
 239  
      * Returns true if the specification is known to be a page specification and
 240  
      * not a component specification. Earlier versions of the framework did not
 241  
      * distinguish between the two, but starting in 2.2, there are seperate XML
 242  
      * entities for pages and components. Pages omit several attributes and
 243  
      * entities related to parameters, as parameters only make sense for
 244  
      * components.
 245  
      * 
 246  
      * @since 2.2
 247  
      */
 248  
     boolean isPageSpecification();
 249  
 
 250  
     /** @since 2.2 * */
 251  
     void setPageSpecification(boolean pageSpecification);
 252  
 
 253  
     /** @since 3.0 * */
 254  
     Resource getSpecificationLocation();
 255  
 
 256  
     /** @since 3.0 * */
 257  
     void setSpecificationLocation(Resource specificationLocation);
 258  
 
 259  
     /**
 260  
      * Adds a new property specification. The name of the property must not
 261  
      * already be defined (and must not change after being added).
 262  
      * 
 263  
      * @since 3.0
 264  
      */
 265  
     void addPropertySpecification(IPropertySpecification spec);
 266  
 
 267  
     /**
 268  
      * Returns a sorted, immutable list of the names of all
 269  
      * {@link org.apache.tapestry.spec.IPropertySpecification}s.
 270  
      * 
 271  
      * @since 3.0
 272  
      */
 273  
     List getPropertySpecificationNames();
 274  
 
 275  
     /**
 276  
      * Returns the named {@link org.apache.tapestry.spec.IPropertySpecification},
 277  
      * or null if no such specification exist.
 278  
      * 
 279  
      * @since 3.0
 280  
      * @see #addPropertySpecification(IPropertySpecification)
 281  
      */
 282  
     IPropertySpecification getPropertySpecification(String name);
 283  
 
 284  
     /**
 285  
      * Adds a {@link InjectSpecification}.
 286  
      * 
 287  
      * @since 4.0
 288  
      */
 289  
 
 290  
     void addInjectSpecification(InjectSpecification spec);
 291  
 
 292  
     /**
 293  
      * Returns the list of {@link InjectSpecification}. Will return an empty
 294  
      * list if no specifications have been added.
 295  
      * 
 296  
      * @since 4.0
 297  
      */
 298  
 
 299  
     List getInjectSpecifications();
 300  
 
 301  
     /**
 302  
      * Returns true if the component is deprecated. Deprecated components
 303  
      * generate a warning when used.
 304  
      * 
 305  
      * @since 4.0
 306  
      */
 307  
 
 308  
     boolean isDeprecated();
 309  
 
 310  
     /**
 311  
      * @since 4.0
 312  
      */
 313  
 
 314  
     void setDeprecated(boolean deprecated);
 315  
 
 316  
     /**
 317  
      * Returns a Set of Strings; the reserved parameter names for the component.
 318  
      * This combines explicit reserved names with formal parameter names. Each
 319  
      * parameter name in the Set will be all lower case (to facilitate a
 320  
      * caseless comparison).
 321  
      * 
 322  
      * @returns an unmodifiable set (of String), possibly empty
 323  
      * @since 4.0
 324  
      */
 325  
 
 326  
     Set getReservedParameterNames();
 327  
 }