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;
018
019import org.apache.hivemind.LocationHolder;
020
021/**
022 * Defines a formal parameter to a component. An <code>IParameterSpecification</code> is contained
023 * by a {@link IComponentSpecification}.
024 * <p>
025 * TBD: Identify arrays in some way.
026 * 
027 * @author glongman@intelligentworks.com
028 */
029public interface IParameterSpecification extends LocationHolder
030{
031    /**
032     * Returns the class name of the expected type of the parameter. The default value is
033     * <code>java.lang.Object</code> which matches anything.
034     */
035    public String getType();
036
037    /**
038     * Returns true if the parameter is required by the component. The default is false, meaning the
039     * parameter is optional.
040     */
041    public boolean isRequired();
042
043    public void setRequired(boolean value);
044
045    /**
046     * Sets the type of value expected for the parameter. This can be left blank to indicate any
047     * type.
048     */
049    public void setType(String value);
050
051    /**
052     * Returns the documentation for this parameter.
053     * 
054     * @since 1.0.9
055     */
056    public String getDescription();
057
058    /**
059     * Sets the documentation for this parameter.
060     * 
061     * @since 1.0.9
062     */
063    public void setDescription(String description);
064
065    /**
066     * Sets the property name (of the component class) to connect the parameter to.
067     */
068    public void setPropertyName(String propertyName);
069
070    /**
071     * Returns the name of the JavaBeans property to connect the parameter to.
072     */
073    public String getPropertyName();
074
075    /**
076     * Returns the default value for the parameter (or null if the parameter has no default value).
077     * Required parameters may not have a default value. The default value is a
078     * <em>binding locator</em> (a prefixed value, as with a binding element).
079     */
080    public String getDefaultValue();
081
082    /**
083     * Sets the default value of the JavaBeans property if no binding is provided
084     */
085    public void setDefaultValue(String defaultValue);
086
087    /**
088     * Returns true if the parameter property should cache the result of the binding.
089     * 
090     * @since 4.0
091     */
092
093    public boolean getCache();
094
095    /** @since 4.0 */
096
097    public void setCache(boolean cache);
098
099    /**
100     * Returns the (primary) name of the parameter.
101     * 
102     * @since 4.0
103     */
104
105    public String getParameterName();
106
107    /**
108     * @since 4.0
109     */
110
111    public void setParameterName(String name);
112
113    /**
114     * Returns a non-null collection of strings for the aliases of the parameter. This is usually an
115     * empty list.
116     * 
117     * @since 4.0
118     */
119
120    public Collection getAliasNames();
121
122    /**
123     * Sets the list of aliases as a comma-seperated list.
124     * 
125     * @param nameList
126     *            a comma seperated list of names, which may be null or empty
127     * @since 4.0
128     */
129
130    public void setAliases(String nameList);
131
132    /**
133     * Returns true if the parameter is deprecated. Deprecated parameter generate a warning when
134     * bound.
135     * 
136     * @since 4.0
137     */
138
139    public boolean isDeprecated();
140
141    /**
142     * @since 4.0
143     */
144
145    public void setDeprecated(boolean deprecated);
146
147}