    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    }