1 package cz.cuni.amis.pogamut.multi.communication.worldview;
2
3 import java.util.Map;
4
5 import cz.cuni.amis.pogamut.base.communication.translator.event.IWorldChangeEvent;
6 import cz.cuni.amis.pogamut.base.communication.worldview.IWorldChangeEventInput;
7 import cz.cuni.amis.pogamut.base.communication.worldview.IWorldView;
8 import cz.cuni.amis.pogamut.base.communication.worldview.event.IWorldEventListener;
9 import cz.cuni.amis.pogamut.base.communication.worldview.object.IWorldObject;
10 import cz.cuni.amis.pogamut.base.communication.worldview.object.IWorldObjectEvent;
11 import cz.cuni.amis.pogamut.base.communication.worldview.object.IWorldObjectEventListener;
12 import cz.cuni.amis.pogamut.base.communication.worldview.object.WorldObjectId;
13 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectDestroyedEvent;
14 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectFirstEncounteredEvent;
15 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectUpdatedEvent;
16 import cz.cuni.amis.pogamut.base.component.bus.IComponentBus;
17 import cz.cuni.amis.pogamut.base.component.bus.exception.ComponentNotRunningException;
18 import cz.cuni.amis.pogamut.base.component.bus.exception.ComponentPausedException;
19 import cz.cuni.amis.pogamut.base.utils.guice.AgentScoped;
20 import cz.cuni.amis.pogamut.base3d.worldview.object.event.WorldObjectAppearedEvent;
21 import cz.cuni.amis.pogamut.base3d.worldview.object.event.WorldObjectDisappearedEvent;
22 import cz.cuni.amis.pogamut.multi.agent.ITeamedAgentId;
23 import cz.cuni.amis.pogamut.multi.communication.worldview.object.ICompositeWorldObject;
24 import cz.cuni.amis.pogamut.multi.communication.worldview.object.ILocalWorldObject;
25 import cz.cuni.amis.pogamut.multi.utils.exception.TimeKeyNotLockedException;
26 import cz.cuni.amis.pogamut.multi.utils.timekey.TimeKey;
27
28 /**
29 * Interface for a World View local to a single agent in a multi-agent system
30 * any implementation must implement the necessary object maps!
31 *
32 * TODO: [srlok] what are the problems using TimeKey? does it always return the information to any TimeKey I may obtain?
33 * Am I supposed to always provide the TimeKey that is Current? What about locking?
34 *
35 * @author srlok
36 *
37 */
38 public interface ILocalWorldView extends IWorldChangeEventInput {
39
40
41 // =========
42 // COMPONENT
43 // =========
44
45 public IComponentBus getEventBus();
46
47 /**
48 * Calls notify without waiting for batches, locks or anything else.
49 */
50 public void notifyImmediately( IWorldChangeEvent event )
51 throws ComponentNotRunningException, ComponentPausedException;
52
53 //=======//
54 //OBJECTS//
55 //=======//
56
57 //GET METHODS//
58 //local-oriented//
59
60 public ITeamedAgentId getAgentId();
61
62 /**
63 * Returns the most current LocalObject. <BR>
64 * Returns the local part of requested WorldObject. A local part for every object contains properties subjective to only one agent.
65 * (like isVisible).
66 * @param objectId
67 * @return
68 */
69 public ILocalWorldObject getLocal( WorldObjectId objectId);
70
71 //////////////////////
72 //composite-oriented//
73 //////////////////////
74
75
76 /**
77 *
78 * @param objectId
79 * @return
80 */
81 public ICompositeWorldObject get( WorldObjectId objectId );
82
83 /**
84 * Returns object with specific id and class, if it exists.
85 * @param <T>
86 * @param objectId
87 * @param clazz
88 * @return The object or null if it does not exist
89 * @throws ClassCastException if the object exists, but is not of specified class
90 */
91 public <T extends ICompositeWorldObject> T get( WorldObjectId objectId, Class<T> clazz);
92
93 /**
94 * Returns a map of all CompositeWorldObjects in the world. <br>
95 * The map is lazy, the Composite objects are created only when a get() method is called.
96 * If you need to iterate over this map and you don't need all of the values
97 * iterate over the keySet.
98 * <br>
99 * The map will contain objects current to timeKey actual on calling of this method.
100 * @return
101 */
102 public Map<WorldObjectId, ICompositeWorldObject> get();
103
104
105
106 /**
107 * Returns all objects sorted according to class. All of the classMaps are lazy-implemented, so the CompositeObject will only be created
108 * on get method. If you need to iterate over the map, but you don't need the actual objects, iterate over the keySet.
109 * Do not hold reference to this map! Always use new getAll() call when you need this map again or you risk that some classMaps will get
110 * new timeKeys. By calling getAll(Class, time != thisTime).
111 * @return
112 */
113 public Map<Class, Map<WorldObjectId, ICompositeWorldObject>> getAll();
114
115
116 /**
117 *
118 * @param <T>
119 * @param type
120 * @return
121 */
122 public <T extends IWorldObject> Map<WorldObjectId, T> getAll(Class<T> type);
123
124
125 //singleton oriented//
126
127 /**
128 *
129 */
130 public <T extends IWorldObject> T getSingle(Class<T> cls);
131
132 //========//
133 //TIME_KEY//
134 //========//
135
136 public boolean setInitialTime( TimeKey timeKey );
137 public boolean setCurrentTime( TimeKey timeKey );
138
139
140 void lockTime(long time);
141 void unlockTime(long time) throws TimeKeyNotLockedException;
142 TimeKey getCurrentTimeKey();
143
144 //=========//
145 //LISTENERS//
146 //=========//
147
148 /**
149 * Adds listener to a specific event (Level A listeners). Note that the event listener must be able
150 * to handle events of the class 'event'.
151 * <p><p>
152 * It is the most general type of listener-registration allowing you to sniff any type of events.
153 * <p><p>
154 * Events passed to the listener are filtered only according to the 'event' class.
155 * <p><p>
156 * <b>WARNING:</b> even though the method does not require templated class and listener, you must be sure
157 * that 'listener' can accept 'eventClass'.
158 *
159 * @param eventClass which event types you want to receive
160 * @param listener where you want to handle these events
161 */
162 public void addEventListener(Class<?> eventClass, IWorldEventListener<?> listener);
163
164 /**
165 * Adds listener to all events that happens on any object of the 'objectClass' (Level B listeners).
166 * <p><p>
167 * Events passed to the listener are filtered according to the 'objectClass'.
168 * <p><p>
169 * <b>WARNING:</b> even though the method does not require templated classes and listener, you must be sure
170 * that 'listener' accepts all events (IWorldObjectEvent) for objects of 'objectClass'.
171 *
172 * @param objectClass which object class you want to listen at
173 * @param eventClass which event class you want to receive
174 * @param listener where you want to handle these events
175 */
176 public void addObjectListener(Class<?> objectClass, IWorldObjectEventListener<?, ?> listener);
177
178 /**
179 * Adds listener to a specified 'event' that occurs on the specific 'objectClass' (Level C listeners).
180 * <p><p>
181 * Events passed to the listener are filtered according to the 'event' and 'objectClass' of the object the event happened upon.
182 * <p><p>
183 * <b>WARNING:</b> even though the method does not require templated classes and listener, you must be sure
184 * that 'listener' accepts 'eventClass' for objects of 'objectClass'.
185 *
186 * <p>
187 * eventClass can be any implementor of {@link IWorldObjectEvent}. E.g.
188 * {@link WorldObjectAppearedEvent}, {@link WorldObjectDestroyedEvent}, {@link WorldObjectDisappearedEvent},
189 * {@link WorldObjectFirstEncounteredEvent} or {@link WorldObjectUpdatedEvent}.
190 * </p>
191 *
192 * @param objectClass which object class you want to listen at
193 * @param eventClass which event class you want to receive
194 * @param listener where you want to handle these events
195 */
196 public void addObjectListener(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener);
197
198 /**
199 * Adds listener to all events that happens on object with specific 'objectId' (Level D listeners).
200 * <p><p>
201 * Events passed to the listener are filtered according to the 'objectId' of the object.
202 * <p><p>
203 * <b>WARNING:</b> you must ensure that 'listener' can accept the event raised on object of specified 'objectId'.
204 *
205 * @param objectId which object you want to listen at
206 * @param listener where you want to handle events
207 */
208 public void addObjectListener(WorldObjectId objectId, IWorldObjectEventListener<?, ?> listener);
209
210 /**
211 * Adds listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
212 * <p><p>
213 * Events passed to the listener are filtered according to the 'event' and 'objectId' of the object.
214 * <p><p>
215 * <b>WARNING:</b> even though the method does not require templated classes and listener, you must be sure
216 * that 'listener' accepts 'eventClass' for objects of specified 'objectId'.
217 *
218 * @param objectId which object you want to listen at
219 * @param eventClass which event classes you want to receive
220 * @param listener where you want to handle these events
221 */
222 public void addObjectListener(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?, ?> listener);
223
224 /**
225 * Removes listener from a specific event (Level A listeners).
226 *
227 * @param eventClass which events class you want to remove the listener from
228 * @param listener you want to remove
229 */
230 public void removeEventListener(Class<?> eventClass, IWorldEventListener<?> listener);
231
232 /**
233 * Removes listener from specific 'objectClass' listening for specified 'event' (Level B listeners).
234 *
235 * @param objectClass class of objects you want the listener to remove from
236 * @param eventClass which events class you want to remove the listener from
237 * @param listener you want to remove
238 */
239 public void removeObjectListener(Class<?> objectClass, IWorldObjectEventListener<?,?> listener);
240
241 /**
242 * Removes listener from specific 'objectClass' listening for specified 'event' (Level C listeners).
243 *
244 * @param objectClass class of objects you want the listener to remove from
245 * @param eventClass which events class you want to remove the listener from
246 * @param listener you want to remove
247 */
248 public void removeObjectListener(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener);
249
250
251 /**
252 * Removes listener from objects with specified 'objectId' (Level D Listeners).
253 *
254 * @param objectId id of object you want the listener to remove from
255 * @param listener you want to remove
256 */
257 public void removeObjectListener(WorldObjectId objectId, IWorldObjectEventListener<?, ?> listener);
258
259 /**
260 * Removes listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
261 *
262 * @param objectId id of object you want the listener to remove from
263 * @param eventClass event class you want to stop receiving in the listener
264 * @param listener you want to remove
265 */
266 public void removeObjectListener(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?, ?> listener);
267
268 /**
269 * Removes listener from every listeners category (from every listener level).
270 * <p><p>
271 * <b>WARNING:</b> Can be time consuming! (Iterating through all levels of listeners.)
272 *
273 * @param listener you want to remove from all listener levels
274 */
275 public void removeListener(IWorldEventListener<?> listener);
276
277 /**
278 * Tests whether the 'listener' is listening to a specific event (Level A listeners).
279 *
280 * @param eventClass which events you want to receive
281 * @param listener that is tested
282 * @return whether the listener is listening
283 */
284 public boolean isListening(Class<?> eventClass, IWorldEventListener<?> listener);
285
286 /**
287 * Tests whether the 'listener' is listening at specified 'objectClass' (Level B listeners).
288 *
289 * @param objectClass where the listener is tested
290 * @param listener that is tested
291 * @return whether the listener is listening
292 */
293 public boolean isListening(Class<?> objectClass, IWorldObjectEventListener<?,?> listener);
294
295 /**
296 * Tests whether the 'listener' is listening at specified 'objectClass' for specified 'event' (Level C listeners).
297 *
298 * @param objectClass where the listener is tested
299 * @param eventClass where the listener is tested
300 * @param listener that is tested
301 * @return whether the listener is listening
302 */
303 public boolean isListening(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener);
304
305
306 /**
307 * Tests whether the 'listener' is listening at specified 'objectId' (Level D Listeners).
308 *
309 * @param objectId where the listener is tested
310 * @param listener that is tested
311 * @return whether the listener is listening
312 */
313 public boolean isListening(WorldObjectId objectId, IWorldObjectEventListener<?, ?> listener);
314
315 /**
316 * Tests whether the 'listener' is listening to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
317 *
318 * @param objectId where the listener is tested
319 * @param eventClass what class is tested
320 * @param listener that is tested
321 * @return whether the listener is listening
322 */
323 public boolean isListening(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?, ?> listener);
324
325 /**
326 * Checks whether this listener is hooked to the world view (at any listener level).
327 * <p><p>
328 * <b>WARNING:</b> Can be time consuming! (Iterating through all levels of listeners.)
329 *
330 * @param listener
331 * @return
332 */
333 public boolean isListening(IWorldEventListener<?> listener);
334
335
336 }