public interface IWorldView extends IWorldChangeEventInput
It assumes that each world description consists of two entites:
IWorldEvent
)IWorldObject
)IWorldEvent
and IWorldObjectEvent
which describes
the changes in the world. User of the world view is allowed to set up listeners for various events as well as objects.
Therefore there are two types of listeners:
IWorldEventListener
- we will refer to them as 'event' listenersIWorldObjectEventListener
- we will refer to them as 'object' listenersIWorldObjectListener
that is easier to use.
addEventListener(Class, IWorldEventListener)
): Primarily - these listeners can be hooked up according to the event class, for instance there is WorldObjectAppearedEvent
that
implements IWorldObjectEvent. Therefore, if you want to be notified about every object that appears in the
field of view of the agent, you should register an implementor of IWorldObjectEventListener
to the class WorldObjectAppearedEvent
.class.
The motivation here is, that the class of event is unique identifier of the event and therefore it may serve as identification for listener registration.
Also notice that IWorldObjectEvent
is extending IWorldEvent
(of course!), therefore by registering a listener to IWorldEvent
.class
will allow you to sniff every events that will happen in the world (or generated by the world view).
Furthermore - there are IWorldObjectEventListener
s that can be registered to receive only events that are happening on some
IWorldObject
. These are:
IWorldView#addObjectListener(Class, IWorldObjectListener)
): listen to all events on a specific class of objects by specifying the class (this is different from the class of the event because
this time we're querying class of the object not the class of the event)IWorldView#addObjectListener(Class, Class, IWorldObjectListener)
): listen to specific event on specific class of objectsIWorldView#addObjectListener(WorldObjectId, IWorldObjectListener)
): listen to all events on specific object via specifying its object idIWorldView#addObjectListener(WorldObjectId, Class, IWorldObjectListener)
): listen to a specific event on the specific object (via object id)The listener notifying scheme follows the rule from "general" listeners to "specific" listeners. The listeners are invoked in this order:
EventListener
)ObjectClassListener
)ObjectClassEventListener
)ObjectListener
)ObjectEventListener
)
When you need to listen on various events, use method annotations (see the links in the list) and AnnotationListenerRegistrator
to automatically hook up listeners for you - note that the AnnotationListenerRegistrator
are currently not supporting inheritance.
Modifier and Type | Method and Description |
---|---|
void |
addEventListener(Class<?> eventClass,
IWorldEventListener<?> listener)
Adds listener to a specific event (Level A listeners).
|
void |
addObjectListener(Class<?> objectClass,
Class<?> eventClass,
IWorldObjectEventListener<?,?> listener)
Adds listener to a specified 'event' that occurs on the specific 'objectClass' (Level C listeners).
|
void |
addObjectListener(Class<?> objectClass,
IWorldObjectEventListener<?,?> listener)
Adds listener to all events that happens on any object of the 'objectClass' (Level B listeners).
|
void |
addObjectListener(WorldObjectId objectId,
Class<?> eventClass,
IWorldObjectEventListener<?,?> listener)
Adds listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
|
void |
addObjectListener(WorldObjectId objectId,
IWorldObjectEventListener<?,?> listener)
Adds listener to all events that happens on object with specific 'objectId' (Level D listeners).
|
Map<WorldObjectId,IWorldObject> |
get()
Returns map with objects inserted according to their id.
|
IWorldObject |
get(WorldObjectId id)
Returns a world object of the specific id (if exists inside the world view).
|
<T extends IWorldObject> |
get(WorldObjectId id,
Class<T> clazz)
Returns a world object of the specific id and class (if exists inside the world view).
|
Map<Class,Map<WorldObjectId,IWorldObject>> |
getAll()
Returns map of all objects that are present in the world view.
|
<T extends IWorldObject> |
getAll(Class<T> type)
Returns map of all objects of a specific type that are present in the world view.
|
IComponentBus |
getEventBus() |
<T extends IWorldObject> |
getSingle(Class<T> cls)
Returns the only instance of required object if present, if there are
more instances of this object then
IllegalArgumentException will be thrown. |
boolean |
isListening(Class<?> objectClass,
Class<?> eventClass,
IWorldObjectEventListener<?,?> listener)
Tests whether the 'listener' is listening at specified 'objectClass' for specified 'event' (Level C listeners).
|
boolean |
isListening(Class<?> eventClass,
IWorldEventListener<?> listener)
Tests whether the 'listener' is listening to a specific event (Level A listeners).
|
boolean |
isListening(Class<?> objectClass,
IWorldObjectEventListener<?,?> listener)
Tests whether the 'listener' is listening at specified 'objectClass' (Level B listeners).
|
boolean |
isListening(IWorldEventListener<?> listener)
Checks whether this listener is hooked to the world view (at any listener level).
|
boolean |
isListening(WorldObjectId objectId,
Class<?> eventClass,
IWorldObjectEventListener<?,?> listener)
Tests whether the 'listener' is listening to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
|
boolean |
isListening(WorldObjectId objectId,
IWorldObjectEventListener<?,?> listener)
Tests whether the 'listener' is listening at specified 'objectId' (Level D Listeners).
|
void |
removeEventListener(Class<?> eventClass,
IWorldEventListener<?> listener)
Removes listener from a specific event (Level A listeners).
|
void |
removeListener(IWorldEventListener<?> listener)
Removes listener from every listeners category (from every listener level).
|
void |
removeObjectListener(Class<?> objectClass,
Class<?> eventClass,
IWorldObjectEventListener<?,?> listener)
Removes listener from specific 'objectClass' listening for specified 'event' (Level C listeners).
|
void |
removeObjectListener(Class<?> objectClass,
IWorldObjectEventListener<?,?> listener)
Removes listener from specific 'objectClass' listening for specified 'event' (Level B listeners).
|
void |
removeObjectListener(WorldObjectId objectId,
Class<?> eventClass,
IWorldObjectEventListener<?,?> listener)
Removes listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).
|
void |
removeObjectListener(WorldObjectId objectId,
IWorldObjectEventListener<?,?> listener)
Removes listener from objects with specified 'objectId' (Level D Listeners).
|
notify, notifyAfterPropagation, notifyImmediately
getComponentId
IComponentBus getEventBus()
void addEventListener(Class<?> eventClass, IWorldEventListener<?> listener)
It is the most general type of listener-registration allowing you to sniff any type of events.
Events passed to the listener are filtered only according to the 'event' class.
WARNING: even though the method does not require templated class and listener, you must be sure that 'listener' can accept 'eventClass'.
eventClass
- which event types you want to receivelistener
- where you want to handle these eventsvoid addObjectListener(Class<?> objectClass, IWorldObjectEventListener<?,?> listener)
Events passed to the listener are filtered according to the 'objectClass'.
WARNING: even though the method does not require templated classes and listener, you must be sure that 'listener' accepts all events (IWorldObjectEvent) for objects of 'objectClass'.
objectClass
- which object class you want to listen ateventClass
- which event class you want to receivelistener
- where you want to handle these eventsvoid addObjectListener(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener)
Events passed to the listener are filtered according to the 'event' and 'objectClass' of the object the event happened upon.
WARNING: even though the method does not require templated classes and listener, you must be sure that 'listener' accepts 'eventClass' for objects of 'objectClass'.
eventClass can be any implementor of IWorldObjectEvent
. E.g.
WorldObjectAppearedEvent
, WorldObjectDestroyedEvent
, WorldObjectDisappearedEvent
,
WorldObjectFirstEncounteredEvent
or WorldObjectUpdatedEvent
.
objectClass
- which object class you want to listen ateventClass
- which event class you want to receivelistener
- where you want to handle these eventsvoid addObjectListener(WorldObjectId objectId, IWorldObjectEventListener<?,?> listener)
Events passed to the listener are filtered according to the 'objectId' of the object.
WARNING: you must ensure that 'listener' can accept the event raised on object of specified 'objectId'.
objectId
- which object you want to listen atlistener
- where you want to handle eventsvoid addObjectListener(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?,?> listener)
Events passed to the listener are filtered according to the 'event' and 'objectId' of the object.
WARNING: even though the method does not require templated classes and listener, you must be sure that 'listener' accepts 'eventClass' for objects of specified 'objectId'.
objectId
- which object you want to listen ateventClass
- which event classes you want to receivelistener
- where you want to handle these eventsvoid removeEventListener(Class<?> eventClass, IWorldEventListener<?> listener)
eventClass
- which events class you want to remove the listener fromlistener
- you want to removevoid removeObjectListener(Class<?> objectClass, IWorldObjectEventListener<?,?> listener)
objectClass
- class of objects you want the listener to remove fromeventClass
- which events class you want to remove the listener fromlistener
- you want to removevoid removeObjectListener(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener)
objectClass
- class of objects you want the listener to remove fromeventClass
- which events class you want to remove the listener fromlistener
- you want to removevoid removeObjectListener(WorldObjectId objectId, IWorldObjectEventListener<?,?> listener)
objectId
- id of object you want the listener to remove fromlistener
- you want to removevoid removeObjectListener(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?,?> listener)
objectId
- id of object you want the listener to remove fromeventClass
- event class you want to stop receiving in the listenerlistener
- you want to removevoid removeListener(IWorldEventListener<?> listener)
WARNING: Can be time consuming! (Iterating through all levels of listeners.)
listener
- you want to remove from all listener levelsboolean isListening(Class<?> eventClass, IWorldEventListener<?> listener)
eventClass
- which events you want to receivelistener
- that is testedboolean isListening(Class<?> objectClass, IWorldObjectEventListener<?,?> listener)
objectClass
- where the listener is testedlistener
- that is testedboolean isListening(Class<?> objectClass, Class<?> eventClass, IWorldObjectEventListener<?,?> listener)
objectClass
- where the listener is testedeventClass
- where the listener is testedlistener
- that is testedboolean isListening(WorldObjectId objectId, IWorldObjectEventListener<?,?> listener)
objectId
- where the listener is testedlistener
- that is testedboolean isListening(WorldObjectId objectId, Class<?> eventClass, IWorldObjectEventListener<?,?> listener)
objectId
- where the listener is testedeventClass
- what class is testedlistener
- that is testedboolean isListening(IWorldEventListener<?> listener)
WARNING: Can be time consuming! (Iterating through all levels of listeners.)
listener
- Map<Class,Map<WorldObjectId,IWorldObject>> getAll()
WARNING: If you will do iteration over the map, you must synchronize on it.
<T extends IWorldObject> Map<WorldObjectId,T> getAll(Class<T> type)
WARNING: If you will do iteration over the map, you must synchronize on it.
type
- <T extends IWorldObject> T getSingle(Class<T> cls)
IllegalArgumentException
will be thrown.
Should be used to obtain "utility" world objects such us "informations about the agent" (that is unique for the agent and as the world view should be used by only one agent...) or some "world statistics object".
T
- cls
- Class of object to be retrievedMap<WorldObjectId,IWorldObject> get()
WARNING: If you will do iteration over the map, you must synchronize on it.
Note that this map contains various objects, therefore you will somehow guess the correct class of the object from its id.
IWorldObject get(WorldObjectId id)
Note that there is no way to tell the correct type of returned object - you have to cast it to a correct class yourself.
id
- objects's id<T extends IWorldObject> T get(WorldObjectId id, Class<T> clazz)
id
- objects's idclazz
- the class of the object to be returnedClassCastException
- if the object with specified id exists, but is not of specified typeCopyright © 2012 AMIS research group, Faculty of Mathematics and Physics, Charles University in Prague, Czech Republic. All Rights Reserved.