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    }