01: // Copyright 2006, 2007 The Apache Software Foundation
02: //
03: // Licensed under the Apache License, Version 2.0 (the "License");
04: // you may not use this file except in compliance with the License.
05: // You may obtain a copy of the License at
06: //
07: // http://www.apache.org/licenses/LICENSE-2.0
08: //
09: // Unless required by applicable law or agreed to in writing, software
10: // distributed under the License is distributed on an "AS IS" BASIS,
11: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12: // See the License for the specific language governing permissions and
13: // limitations under the License.
14:
15: package org.apache.tapestry.annotations;
16:
17: import static java.lang.annotation.ElementType.FIELD;
18: import static java.lang.annotation.RetentionPolicy.RUNTIME;
19:
20: import java.lang.annotation.Documented;
21: import java.lang.annotation.Retention;
22: import java.lang.annotation.Target;
23:
24: import org.apache.tapestry.TapestryConstants;
25: import org.apache.tapestry.services.BindingFactory;
26:
27: /**
28: * Annotation placed on a field to indicate that it is, in fact, an parameter. Parameters may be
29: * optional or required. Required parameters must be bound.
30: */
31: @Target(FIELD)
32: @Documented
33: @Retention(RUNTIME)
34: public @interface Parameter {
35:
36: /**
37: * The name of the parameter. If not specified, the name of the parameter is derived from the
38: * name of the field (after stripping off leading punctuation) from the field name.
39: */
40: String name() default "";
41:
42: /**
43: * If true, the parameter is required and and must be bound. If false (the default), then the
44: * parameter is optional.
45: */
46: boolean required() default false;
47:
48: /**
49: * If true (the default), then the value for the parameter is cached while the component is,
50: * itself, rendering. Values from invariant bindings (such as literal strings) are always
51: * cached, regardless of this setting. Set this attribute to false to force the parameter to be
52: * {@link org.apache.tapestry.Binding#get() re-read} every time the field is accessed, even
53: * while the component is rendering.
54: */
55: boolean cache() default true;
56:
57: /**
58: * The default value for the parameter if not bound (at not the empty string). This is a binding
59: * expression, typically the name of a property of the component to bind.
60: */
61: String value() default "";
62:
63: /**
64: * The default binding prefix for the parameter, if no specific binding prefix is provided with
65: * the binding. There is <em>rarely</em> a reason to override this. Typically, non-standard
66: * default binding prefixes are paired with specific {@link BindingFactory} implementations, and
67: * used with parameters whose name reflects the binding prefix.
68: */
69: String defaultPrefix() default TapestryConstants.PROP_BINDING_PREFIX;
70:
71: /**
72: * Used to mark a parameter as requiring earlier initialization than other parameters. This is
73: * used when default bindings for secondary parameters rely on a principal parameter, which
74: * itself may have a default value. This ensures that the binding for the principal parameter(s)
75: * are initialized, possibly involving a defaulter method, before the secondary parameters are
76: * initialized (as they may need to know if the principal parameter is bound, and what type of
77: * value it is bound to). This is rarely used, and it is highly unlikely a single component
78: * would have more than a single principal parameter.
79: */
80: boolean principal() default false;
81: }
|