1 /*
2 Copyright 2007 Ramon Servadei
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16 package fulmine.event;
17
18 import java.util.List;
19
20 import fulmine.IAddressable;
21 import fulmine.IDescriptor;
22 import fulmine.ILifeCycle;
23 import fulmine.event.listener.IEventListener;
24 import fulmine.event.listener.IPriorityEventListener;
25
26 /**
27 * An object that generates {@link IEvent} objects. The events are distributed
28 * to {@link IEventListener} instances. The listeners need to be registered with
29 * the source via the {@link #addListener(IEventListener)} method.
30 *
31 * @author Ramon Servadei
32 *
33 */
34 public interface IEventSource extends IDescriptor, ILifeCycle, IAddressable
35 {
36 /**
37 * Get the list of {@link IEventListener} instances observing this. The list
38 * is the order of registration and the notification order for any
39 * {@link IEvent} raised by this event source.
40 * <p>
41 * The list is not modifiable.
42 *
43 * @return an <b>unmodifiable</b> list of listeners, or <code>null</code> if
44 * there are no listeners
45 */
46 List<IEventListener> getListeners();
47
48 /**
49 * Add the listener to the end of the list of listeners registered against
50 * this. If the listener is an {@link IPriorityEventListener}, it is added
51 * to the beginning of the list.
52 * <p>
53 * Listeners are reference counted. Adding the same listener multiple times
54 * simply increments a reference count of the listener instance; if a
55 * listener is added twice, it must be removed twice for the listener
56 * instance reference to be removed from the internal list.
57 *
58 * @param listener
59 * the listener to add
60 * @return <code>true</code> if the listener instance was added (there were
61 * no reference counts for it), <code>false</code> if it already
62 * existed (the reference count was incremented)
63 */
64 boolean addListener(IEventListener listener);
65
66 /**
67 * Remove the listener from the list of listeners registered against this.
68 * If this is the last listener being removed, the list of listeners is set
69 * to <code>null</code>.
70 * <p>
71 * Listeners are reference counted. When removing a listener, this method
72 * decrements the reference count until there are no more references, at
73 * which point the listener instance reference is actually removed.
74 *
75 * @param listener
76 * the listener to remove
77 * @return <code>true</code> if the listener was found and the reference
78 * count was 0 and it was removed, <code>false</code> otherwise
79 */
80 boolean removeListener(IEventListener listener);
81
82 /**
83 * Remove all listeners registered for receiving {@link IEvent} events
84 * originating from this.
85 *
86 * @return the list of listeners removed
87 */
88 List<IEventListener> removeListeners();
89
90 /**
91 * A byte identifying the event source group id. This will be the id of the
92 * {@link EventProcessor} that will distribute the events from this source.
93 *
94 * @return a byte for the {@link EventProcessor} servicing this.
95 */
96 byte getEventSourceGroupId();
97
98 /**
99 * Add the event to the source and notify any registered
100 * {@link IEventListener} instances with the event. The manner of activating
101 * listeners with the event may be synchronous or asynchronous; it is the
102 * implementation that decides this.
103 *
104 * @param event
105 * the event to pass on to the registered listeners
106 */
107 void addEvent(IEvent event);
108 }