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 }