KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > beehive > controls > api > events > EventSet


1 package org.apache.beehive.controls.api.events;
2 /*
3  * Copyright 2004 The Apache Software Foundation.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  * $Header:$
18  */
19
20 import java.lang.annotation.ElementType JavaDoc;
21 import java.lang.annotation.Retention JavaDoc;
22 import java.lang.annotation.RetentionPolicy JavaDoc;
23 import java.lang.annotation.Target JavaDoc;
24
25 /**
26  * The EventSet annotation type is used to mark an interface that defines a group of events
27  * associated with a Java Control. By convention, event interfaces are defined as inner
28  * classes on the Java Control public interface. Each method defined within a
29  * event interface indicates an event that can be delivered by the control.
30  * <p>
31  * Here is a simple example:
32  * <code><pre>
33  * public interface MyControl extends org.apache.beehive.controls.api.Control
34  * {
35  * <sp>@EventSet
36  * public interface MyEvents
37  * {
38  * public void anEvent();
39  * }
40  *
41  * ...
42  * }
43  * </pre></code>
44  * This will declare an event interface named <code>MyEvents</code> that declares a single
45  * event: <code>anEvent</code>
46  *
47  * The declaration of an EventSet for a control also means that the associated Control
48  * JavaBean will have listener registration/deregistration APIs. The name of these
49  * APIs will be <i>add/remove<EventSetName>Listener</i>, and the argument will be an
50  * listener instance that implements the EventSet interface.
51  * <p>
52  * The above example would result in the following APIs on <code>MyControlBean</code>
53  *
54  * <code><pre>
55  * public class MyControlBean implements MyControl
56  * {
57  * ...
58  * public void addMyEventsListener(MyEvents listener) { ... }
59  * public void removeMyEventsListener(MyEvents listener) { ... }
60  * </pre></code>
61  */
62 @Retention JavaDoc(RetentionPolicy.RUNTIME)
63 @Target JavaDoc({ElementType.TYPE})
64 public @interface EventSet
65 {
66     /**
67      * Defines whether the events defined by the interface are unicast events. A unicast
68      * event set may have only a single listener registered to receive events for any
69      * given bean instance. Any attempt to register additional listeners will result in
70      * a <code>java.util.TooManyListenersException</code> being thrown by the event
71      * listener registration method.
72      * <p>
73      * If an event set provides multicast support (the default), then it may only declare
74      * event methods that have a <code>void</code> return type. Unicast event sets may
75      * support event return values, that will be provided by the (single) registered
76      * listener.
77      */
78     public boolean unicast() default false;
79 }
80
Popular Tags