001 // Copyright 2006, 2007, 2008, 2009 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.tapestry5.annotations;
016
017 import org.apache.tapestry5.BindingConstants;
018 import org.apache.tapestry5.ioc.annotations.UseWith;
019
020 import java.lang.annotation.Documented;
021 import static java.lang.annotation.ElementType.FIELD;
022 import java.lang.annotation.Retention;
023 import static java.lang.annotation.RetentionPolicy.RUNTIME;
024 import java.lang.annotation.Target;
025
026 import static org.apache.tapestry5.ioc.annotations.AnnotationUseContext.*;
027
028 /**
029 * Annotation placed on a field to indicate that it is, in fact, a component parameter. Parameters may be optional or
030 * required. Required parameters must be bound.
031 */
032 @Target(FIELD)
033 @Documented
034 @Retention(RUNTIME)
035 @UseWith({COMPONENT,MIXIN})
036 public @interface Parameter
037 {
038
039 /**
040 * The name of the parameter. If not specified, the name of the parameter is derived from the name of the field
041 * (after stripping off leading and trailing punctuation).
042 */
043 String name() default "";
044
045 /**
046 * If true, the parameter is required and and must be bound. If false (the default), then the parameter is
047 * optional.
048 */
049 boolean required() default false;
050
051 /**
052 * If false, and the parameter <em>is</em> bound, then the value for the parameter must not be null. The default is
053 * true, to allow nulls. This is different than required, in that the parameter may be bound, but bound to a null
054 * value.
055 */
056 boolean allowNull() default true;
057
058 /**
059 * If true (the default), then the value for the parameter is cached while the component is, itself, rendering.
060 * Values from invariant bindings (such as literal strings) are always cached, regardless of this setting. Set this
061 * attribute to false to force the parameter to be {@linkplain org.apache.tapestry5.Binding#get() re-read} every
062 * time the field is accessed, even while the component is rendering.
063 */
064 boolean cache() default true;
065
066 /**
067 * The default value for the parameter if not bound (and not the empty string). This is a binding expression,
068 * typically the name of a property of the component to bind.
069 */
070 String value() default "";
071
072 /**
073 * The default binding prefix for the parameter, if no specific binding prefix is provided with the binding. There
074 * is <em>rarely</em> a reason to override this. Typically, non-standard default binding prefixes are paired with
075 * specific {@link org.apache.tapestry5.services.BindingFactory} implementations, and used with parameters whose
076 * name reflects the binding prefix.
077 *
078 * @see org.apache.tapestry5.BindingConstants
079 */
080 String defaultPrefix() default BindingConstants.PROP;
081
082 /**
083 * Used to mark a parameter as requiring earlier initialization than other parameters. This is used when default
084 * bindings for secondary parameters rely on a principal parameter, which itself may have a default value. This
085 * ensures that the binding for the principal parameter(s) are initialized, possibly involving a defaulter method,
086 * before the secondary parameters are initialized (as they may need to know if the principal parameter is bound,
087 * and what type of value it is bound to). This is rarely used, and it is highly unlikely a single component would
088 * have more than a single principal parameter.
089 */
090 boolean principal() default false;
091
092 /**
093 * Used to create a default binding, connecting the parameter to a property of the container whose property name
094 * matches the id of the component. This is frequently used for form element components. This default binding is
095 * only used if there is no matching container property.
096 *
097 * @see org.apache.tapestry5.services.ComponentDefaultProvider#defaultBinding(String,
098 * org.apache.tapestry5.ComponentResources)
099 */
100 boolean autoconnect() default false;
101 }