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.RetentionPolicy.RUNTIME;
18:
19: import java.lang.annotation.Documented;
20: import java.lang.annotation.ElementType;
21: import java.lang.annotation.Retention;
22: import java.lang.annotation.Target;
23:
24: /**
25: * Marks a method as a handler for a client side event. The handler method will be invoked when a
26: * component triggers an event. Filters on the type of event and on the originating component ensure
27: * that only the appropriate methods are invoked.
28: * <p>
29: * Client events include a <em>context</em> of one or more values. These context values are
30: * included in the action URI. The values are optionally supplied to the handler method as
31: * parameters. Automatic type coercions from string to the type of the actual parameter occur.
32: * <p>
33: * Handlers may return a value. Returning a non-null value will abort the handling of the event, and
34: * will usually control the response sent to the client web browser. The details are somewhat
35: * specific to the type of event and the component involved.
36: * <p>
37: * If a handler is not found within the originating component (or no handler aborts the event
38: * handling), then handlers within the containing component will be searched. This continues up the
39: * page hierarchy. In some cases, having no handlers (or no aborting handlers) is considered
40: * acceptible; in others, it is an error. Again, this is defined by the type of originating
41: * component, and the type of event.
42: * <p>
43: * <strong>If you fail to provide filters on either component or event type, then your method will
44: * be invoked for all component events, possibly including events that bubble up from embedded
45: * sub-components. </strong>
46: */
47: @Target(ElementType.METHOD)
48: @Retention(RUNTIME)
49: @Documented
50: public @interface OnEvent {
51:
52: /**
53: * The event types to match. The handler will only be invoked if the client event type matches
54: * the value. If omitted, the default is to match any event. Most components emit, at most, one
55: * event named "action".
56: */
57: String value() default "";
58:
59: /**
60: * The local id of the component from which the event originates. If not specified, then the
61: * default is to match any component. If an event from a component is not handled in the
62: * component's container, it is re-triggered inside the component's grand-container and will
63: * appear to originate from the container. Thus events that escape a component will appear to
64: * originate in the component's container, and so forth.
65: */
66: String component() default "";
67:
68: }
|