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.listener;
17
18 import fulmine.event.EventProcessor;
19 import fulmine.event.IEvent;
20 import fulmine.event.IEventSource;
21
22 /**
23 * A listener processes notifications from {@link IEventSource} instances. The
24 * notifications are encapsulated in {@link IEvent} instances and are received
25 * via the {@link #update(IEvent)} method.
26 * <p>
27 * A listener is required to supply the class of the {@link IEvent} instances it
28 * can process. Before an event is passed into the {@link #update(IEvent)}
29 * method, the class of the event is checked against those returned from
30 * {@link #getEventTypeFilter()}. If the event class is <i>assignment
31 * compatible</i> with any contained in {@link #getEventTypeFilter()} then the
32 * {@link #update(IEvent)} method is called with the event.
33 * <p>
34 * If a listener is registered against multiple {@link IEventSource} instances,
35 * the notifications may be executed by different {@link EventProcessor}
36 * instances (different thread contexts) and so the {@link #update(IEvent)}
37 * method would need to be thread aware.
38 * <p>
39 * The listener also receives a notification when it has been added to and
40 * removed from an {@link IEventSource}.
41 *
42 * @author Ramon Servadei
43 */
44 public interface IEventListener
45 {
46 /**
47 * An update has occurred that this listener is interested in.
48 * {@link IEventSource} instances are bound to {@link EventProcessor}
49 * instances so the same thread will execute this method for events
50 * originating from the same event source. This does not mean that this
51 * method is thread safe; this method may be run by multiple
52 * {@link EventProcessor} instances and so should be thread aware as
53 * appropriate.
54 * <p>
55 * This method can throw any {@link Exception} and processing will not be
56 * interrupted. The {@link EventProcessor} will handle the exception.
57 *
58 * @param event
59 * the event encapsulating the update.
60 */
61 void update(IEvent event);
62
63 /**
64 * The listener receives this when it has been added as a listener to an
65 * event source via {@link IEventSource#addListener(IEventListener)}.
66 *
67 * @param source
68 * the source that this listener will receive events from.
69 */
70 void addedAsListenerFor(IEventSource source);
71
72 /**
73 * The listener receives this when it has been removed as a listener from an
74 * event source via {@link IEventSource#removeListener(IEventListener)}.
75 *
76 * @param source
77 * the source that this listener will no longer receive events
78 * from.
79 */
80 void removedAsListenerFrom(IEventSource source);
81
82 /**
83 * Get the classes of {@link IEvent} instances this listener can process.
84 * The {@link #update(IEvent)} method will only be called with
85 * {@link IEvent} instances whose {@link Class} is <i>assignment
86 * compatible</i> with any contained in this array.
87 * <p>
88 * This is an event filtering mechanism. An {@link IEventSource} may
89 * generate many types of {@link IEvent} instances but a listener may only
90 * be interested in one type. By specifying the types of events the listener
91 * is interested in using this method, the listener effectively filters out
92 * unwanted events.
93 * <p>
94 * If the filter is dynamic then this method must be thread aware.
95 *
96 * @return an array of {@link Class} objects that determine the types of
97 * {@link IEvent} instances this listener can process
98 */
99 Class<? extends IEvent>[] getEventTypeFilter();
100 }