001    // Copyright 2006, 2007 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.tapestry.annotations;
016    
017    import org.apache.tapestry.TapestryConstants;
018    import org.apache.tapestry.services.BindingFactory;
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    /**
027     * Annotation placed on a field to indicate that it is, in fact, an parameter. Parameters may be optional or required.
028     * Required parameters must be bound.
029     */
030    @Target(FIELD)
031    @Documented
032    @Retention(RUNTIME)
033    public @interface Parameter
034    {
035    
036        /**
037         * The name of the parameter. If not specified, the name of the parameter is derived from the name of the field
038         * (after stripping off leading punctuation) from the field name.
039         */
040        String name() default "";
041    
042        /**
043         * If true, the parameter is required and and must be bound. If false (the default), then the parameter is
044         * optional.
045         */
046        boolean required() default false;
047    
048        /**
049         * If true (the default), then the value for the parameter is cached while the component is, itself, rendering.
050         * Values from invariant bindings (such as literal strings) are always cached, regardless of this setting. Set this
051         * attribute to false to force the parameter to be {@link org.apache.tapestry.Binding#get() re-read} every time the
052         * field is accessed, even while the component is rendering.
053         */
054        boolean cache() default true;
055    
056        /**
057         * The default value for the parameter if not bound (at not the empty string). This is a binding expression,
058         * typically the name of a property of the component to bind.
059         */
060        String value() default "";
061    
062        /**
063         * The default binding prefix for the parameter, if no specific binding prefix is provided with the binding. There
064         * is <em>rarely</em> a reason to override this. Typically, non-standard default binding prefixes are paired with
065         * specific {@link BindingFactory} implementations, and used with parameters whose name reflects the binding
066         * prefix.
067         */
068        String defaultPrefix() default TapestryConstants.PROP_BINDING_PREFIX;
069    
070        /**
071         * Used to mark a parameter as requiring earlier initialization than other parameters. This is used when default
072         * bindings for secondary parameters rely on a principal parameter, which itself may have a default value. This
073         * ensures that the binding for the principal parameter(s) are initialized, possibly involving a defaulter method,
074         * before the secondary parameters are initialized (as they may need to know if the principal parameter is bound,
075         * and what type of value it is bound to). This is rarely used, and it is highly unlikely a single component would
076         * have more than a single principal parameter.
077         */
078        boolean principal() default false;
079    }