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