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 015package org.apache.tapestry.spec; 016 017import java.util.Collection; 018import java.util.List; 019import java.util.Set; 020 021import org.apache.hivemind.Locatable; 022import org.apache.hivemind.LocationHolder; 023import org.apache.hivemind.Resource; 024import 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 */ 051public 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}