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 }