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 fulmine.IAddressable;
19 import fulmine.IDescriptor;
20 import fulmine.event.listener.IEventListener;
21
22 /**
23 * An event represents a change that needs to be broadcasted to consumers. An
24 * event is generated by an {@link IEventSource} and is consumed by
25 * {@link IEventListener} objects. These listeners are registered against the
26 * source using the {@link IEventSource#addListener(IEventListener)} method.
27 *
28 * @author Ramon Servadei
29 *
30 */
31 public interface IEvent extends Cloneable, IDescriptor, IAddressable
32 {
33 /**
34 * Get the event source that generated this event
35 *
36 * @return the source that generated the event
37 */
38 IEventSource getSource();
39
40 /**
41 * Get the event frame of this event.
42 *
43 * @return the {@link IEventFrameExecution} that identifies the frame this
44 * event occurred in.
45 */
46 IEventFrameExecution getFrame();
47
48 /**
49 * Get the event frame execution that <u>directly caused</u> this event to
50 * occur.
51 * <p>
52 * An event occurs in its own event frame but it may have been caused by an
53 * event from another frame. This other frame is known as the 'driving'
54 * frame and directly causes this event. In this paradigm, where one event
55 * can cause another event to occur but in a separate event frame execution,
56 * it is sometimes necessary to know the frame of the first event so that
57 * the 2 events can be linked together.
58 *
59 * @return an {@link IEventFrameExecution} that is the event frame execution
60 * of the event that caused this event to occur.
61 */
62 IEventFrameExecution getDrivingFrame();
63
64 /**
65 * Clone this.
66 *
67 * @see Object#clone)_
68 * @return a clone of this
69 */
70 Object clone() throws CloneNotSupportedException;
71
72 /**
73 * Set the 'trigger event'. This is an event that is added to the context's
74 * {@link IEventManager} queue <b>after</b> this event has been processed.
75 *
76 * @param triggerEvent
77 * the trigger event that will be queued <b>after</b> this event
78 * has been processed.
79 */
80 void setTriggerEvent(IEvent triggerEvent);
81
82 /**
83 * Get the 'trigger event'. This is an event that is added to the context's
84 * {@link IEventManager} queue <b>after</b> this event has been processed.
85 *
86 * @return the trigger event to queue <b>after</b> this event has been
87 * processed, or <code>null</code> if there is not a trigger event.
88 */
89 IEvent getTriggerEvent();
90 }