1
2 package cz.cuni.amis.pogamut.multi.communication.worldview;
3
4 import cz.cuni.amis.pogamut.base.communication.worldview.event.IWorldEventListener;
5 import cz.cuni.amis.pogamut.base.communication.worldview.object.IWorldObjectEvent;
6 import cz.cuni.amis.pogamut.base.communication.worldview.object.IWorldObjectEventListener;
7 import cz.cuni.amis.pogamut.base.communication.worldview.object.WorldObjectId;
8 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectDestroyedEvent;
9 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectFirstEncounteredEvent;
10 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectUpdatedEvent;
11 import cz.cuni.amis.pogamut.base.component.lifecyclebus.ILifecycleBus;
12 import cz.cuni.amis.pogamut.base.utils.guice.AgentTeamScoped;
13 import cz.cuni.amis.pogamut.base3d.worldview.object.event.WorldObjectAppearedEvent;
14 import cz.cuni.amis.pogamut.base3d.worldview.object.event.WorldObjectDisappearedEvent;
15 import cz.cuni.amis.pogamut.multi.agent.ITeamId;
16 import cz.cuni.amis.pogamut.multi.communication.worldview.object.ISharedWorldObject;
17 import cz.cuni.amis.pogamut.multi.communication.worldview.object.IStaticWorldObject;
18 import cz.cuni.amis.pogamut.multi.utils.timekey.TimeKey;
19
20 /**
21 * Interface for WorldViews for multi-agent systems
22 * @author srlok
23 *
24 */
25 public interface ISharedWorldView extends ISharedWorldChangeEventInput {
26
27 /**
28 * This method is called when a new localWorldView is created and wants to use this sharedWorldView,
29 * the method registers the LocalWorldView with the sharedWorldView's sharedComponentBus and also
30 * internally stores the information about which WorldViews are registered to it.
31 *
32 * @param localWV The local WorldView to to register.
33 * @param bus ILifecycleBus of the corresponding LocalWorldView
34 */
35 public void registerLocalWorldView( ILocalWorldView localWV, ILifecycleBus bus);
36
37 // ======
38 // EVENTS
39 // ======
40
41
42 //TODO think about adding 1 listener level (specific agent)
43
44 /**
45 * Adds listener to a specific event (Level A listeners). Note that the event listener must be able
46 * to handle events of the class 'event'.
47 * <p><p>
48 * It is the most general type of listener-registration allowing you to sniff any type of events.
49 * <p><p>
50 * Events passed to the listener are filtered only according to the 'event' class.
51 * <p><p>
52 * <b>WARNING:</b> even though the method does not require templated class and listener, you must be sure
53 * that 'listener' can accept 'eventClass'.
54 *
55 * @param eventClass which event types you want to receive
56 * @param listener where you want to handle these events
57 */
58 public void addEventListener(Class<?> eventClass, IWorldEventListener<?> listener);
59
60 /**
61 * Adds listener to all events that happens on any object of the 'objectClass' (Level B listeners).
62 * <p><p>
63 * Events passed to the listener are filtered according to the 'objectClass'.
64 * <p><p>
65 * <b>WARNING:</b> even though the method does not require templated classes and listener, you must be sure
66 * that 'listener' accepts all events (IWorldObjectEvent) for objects of 'objectClass'.
67 *
68 * @param objectClass which object class you want to listen at
69 * @param eventClass which event class you want to receive
70 * @param listener where you want to handle these events
71 */
72 public void addObjectListener(Class<?> objectClass, IWorldObjectEventListener<?, ?> listener);
73
74 /**
75 * Adds listener to a specified 'event' that occurs on the specific 'objectClass' (Level C listeners).
76 * <p><p>
77 * Events passed to the listener are filtered according to the 'event' and 'objectClass' of the object the event happened upon.
78 * <p><p>
79 * <b>WARNING:</b> even though the method does not require templated classes and listener, you must be sure
80 * that 'listener' accepts 'eventClass' for objects of 'objectClass'.
81 *
82 * <p>
83 * eventClass can be any implementor of {@link IWorldObjectEvent}. E.g.
84 * {@link WorldObjectAppearedEvent}, {@link WorldObjectDestroyedEvent}, {@link WorldObjectDisappearedEvent},
85 * {@link WorldObjectFirstEncounteredEvent} or {@link WorldObjectUpdatedEvent}.
86 * </p>
87 *
88 * @param objectClass which object class you want to listen at
89 * @param eventClass which event class you want to receive
90 * @param listener where you want to handle these events
91 */
92 public void addObjectListener(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener);
93
94 /**
95 * Adds listener to all events that happens on object with specific 'objectId' (Level D listeners).
96 * <p><p>
97 * Events passed to the listener are filtered according to the 'objectId' of the object.
98 * <p><p>
99 * <b>WARNING:</b> you must ensure that 'listener' can accept the event raised on object of specified 'objectId'.
100 *
101 * @param objectId which object you want to listen at
102 * @param listener where you want to handle events
103 */
104 public void addObjectListener(WorldObjectId objectId, IWorldObjectEventListener<?, ?> listener);
105
106 /**
107 * Adds listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
108 * <p><p>
109 * Events passed to the listener are filtered according to the 'event' and 'objectId' of the object.
110 * <p><p>
111 * <b>WARNING:</b> even though the method does not require templated classes and listener, you must be sure
112 * that 'listener' accepts 'eventClass' for objects of specified 'objectId'.
113 *
114 * @param objectId which object you want to listen at
115 * @param eventClass which event classes you want to receive
116 * @param listener where you want to handle these events
117 */
118 public void addObjectListener(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?, ?> listener);
119
120 /**
121 * Removes listener from a specific event (Level A listeners).
122 *
123 * @param eventClass which events class you want to remove the listener from
124 * @param listener you want to remove
125 */
126 public void removeEventListener(Class<?> eventClass, IWorldEventListener<?> listener);
127
128 /**
129 * Removes listener from specific 'objectClass' listening for specified 'event' (Level B listeners).
130 *
131 * @param objectClass class of objects you want the listener to remove from
132 * @param eventClass which events class you want to remove the listener from
133 * @param listener you want to remove
134 */
135 public void removeObjectListener(Class<?> objectClass, IWorldObjectEventListener<?,?> listener);
136
137 /**
138 * Removes listener from specific 'objectClass' listening for specified 'event' (Level C listeners).
139 *
140 * @param objectClass class of objects you want the listener to remove from
141 * @param eventClass which events class you want to remove the listener from
142 * @param listener you want to remove
143 */
144 public void removeObjectListener(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener);
145
146
147 /**
148 * Removes listener from objects with specified 'objectId' (Level D Listeners).
149 *
150 * @param objectId id of object you want the listener to remove from
151 * @param listener you want to remove
152 */
153 public void removeObjectListener(WorldObjectId objectId, IWorldObjectEventListener<?, ?> listener);
154
155 /**
156 * Removes listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
157 *
158 * @param objectId id of object you want the listener to remove from
159 * @param eventClass event class you want to stop receiving in the listener
160 * @param listener you want to remove
161 */
162 public void removeObjectListener(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?, ?> listener);
163
164 /**
165 * Removes listener from every listeners category (from every listener level).
166 * <p><p>
167 * <b>WARNING:</b> Can be time consuming! (Iterating through all levels of listeners.)
168 *
169 * @param listener you want to remove from all listener levels
170 */
171 public void removeListener(IWorldEventListener<?> listener);
172
173 /**
174 * Tests whether the 'listener' is listening to a specific event (Level A listeners).
175 *
176 * @param eventClass which events you want to receive
177 * @param listener that is tested
178 * @return whether the listener is listening
179 */
180 public boolean isListening(Class<?> eventClass, IWorldEventListener<?> listener);
181
182 /**
183 * Tests whether the 'listener' is listening at specified 'objectClass' (Level B listeners).
184 *
185 * @param objectClass where the listener is tested
186 * @param listener that is tested
187 * @return whether the listener is listening
188 */
189 public boolean isListening(Class<?> objectClass, IWorldObjectEventListener<?,?> listener);
190
191 /**
192 * Tests whether the 'listener' is listening at specified 'objectClass' for specified 'event' (Level C listeners).
193 *
194 * @param objectClass where the listener is tested
195 * @param eventClass where the listener is tested
196 * @param listener that is tested
197 * @return whether the listener is listening
198 */
199 public boolean isListening(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener);
200
201
202 /**
203 * Tests whether the 'listener' is listening at specified 'objectId' (Level D Listeners).
204 *
205 * @param objectId where the listener is tested
206 * @param listener that is tested
207 * @return whether the listener is listening
208 */
209 public boolean isListening(WorldObjectId objectId, IWorldObjectEventListener<?, ?> listener);
210
211 /**
212 * Tests whether the 'listener' is listening to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
213 *
214 * @param objectId where the listener is tested
215 * @param eventClass what class is tested
216 * @param listener that is tested
217 * @return whether the listener is listening
218 */
219 public boolean isListening(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?, ?> listener);
220
221 /**
222 * Checks whether this listener is hooked to the world view (at any listener level).
223 * <p><p>
224 * <b>WARNING:</b> Can be time consuming! (Iterating through all levels of listeners.)
225 *
226 * @param listener
227 * @return
228 */
229 public boolean isListening(IWorldEventListener<?> listener);
230
231 // =======
232 // OBJECTS
233 // =======
234
235 /**
236 * Returns only the static part of a requested object, static part of each objects only contains properties,
237 * that will NOT be changed over time. Therefore the static part of each object is immutable and always up-to-date.
238 * @param id - WorldObjectId of the entire WorldObject
239 */
240 public IStaticWorldObject getStatic(WorldObjectId id);
241
242 /**
243 * Returns the shared part of a requested object. Shared part of every worldObject contains properties, that are relevant
244 * to multiple agents (usually a team) and are not subjective in nature (every agent sees them differently).
245 * Good example is a boolean property isSpawned . Also note, that many shared properties are computed from other knowledge
246 * about the object (isVisible => isSpawned). For this reason, the value of a shared property can get "dirty" over time, so don't
247 * forget to check if your property is up-to-date.
248 * @param teamId
249 * @param objectId
250 * @return
251 */
252 public ISharedWorldObject getShared(ITeamId teamId, WorldObjectId objectId, TimeKey time);
253
254
255 }