cz.cuni.amis.pogamut.base.communication.worldview
Interface IWorldView

All Superinterfaces:

IComponent, IWorldChangeEventInput

All Known Subinterfaces:

ILockableVisionWorldView, ILockableWorldView, IVisionWorldView

All Known Implementing Classes:

AbstractWorldView, BatchAwareWorldView, EventDrivenWorldView, LockableBatchAwareWorldView, LockableWorldView, SyncLockableBatchAwareWorldView, UT2004LockableWorldView, UT2004SyncLockableWorldView, UT2004WorldView, VisionWorldView

public interface IWorldView
extends IWorldChangeEventInput

Interface for the world view.

It assumes that each world description consists of two entites:

1. actual events described by (IWorldEvent)
2. existing objects described by (IWorldObject)

The world view is designed to accept 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:

1. IWorldEventListener - we will refer to them as 'event' listeners
2. IWorldObjectEventListener - we will refer to them as 'object' listeners
   note that there are also a descendant IWorldObjectListener that is easier to use.

Generally, the world view provides 5 methods user may use to hook up the listener of a various level of specificity.

• Level A listeners (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 IWorldObjectEventListeners that can be registered to receive only events that are happening on some IWorldObject. These are:

• Level B listeners (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)
• Level C listeners (IWorldView#addObjectListener(Class, Class, IWorldObjectListener)): listen to specific event on specific class of objects
• Level D listeners (IWorldView#addObjectListener(WorldObjectId, IWorldObjectListener)): listen to all events on specific object via specifying its object id
• Level E listeners (IWorldView#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:

1. Level A listeners (EventListener)
2. Level B listeners (ObjectClassListener)
3. Level C listeners (ObjectClassEventListener)
4. Level D listeners (ObjectListener)
5. Level E listeners (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.

Method Summary

void	addEventListener(java.lang.Class<?> eventClass, IWorldEventListener<?> listener) Adds listener to a specific event (Level A listeners).
void	addObjectListener(java.lang.Class<?> objectClass, java.lang.Class<?> eventClass, IWorldObjectEventListener<?,?> listener) Adds listener to a specified 'event' that occurs on the specific 'objectClass' (Level C listeners).
void	addObjectListener(java.lang.Class<?> objectClass, IWorldObjectEventListener<?,?> listener) Adds listener to all events that happens on any object of the 'objectClass' (Level B listeners).
void	addObjectListener(WorldObjectId objectId, java.lang.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).
java.util.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).
java.util.Map<java.lang.Class,java.util.Map<WorldObjectId,IWorldObject>>	getAll() Returns map of all objects that are present in the world view.
<T extends IWorldObject> java.util.Map<WorldObjectId,T>	getAll(java.lang.Class<T> type) Returns map of all objects of a specific type that are present in the world view.
IComponentBus	getEventBus()
<T extends IWorldObject> T	getSingle(java.lang.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(java.lang.Class<?> objectClass, java.lang.Class<?> eventClass, IWorldObjectEventListener<?,?> listener) Tests whether the 'listener' is listening at specified 'objectClass' for specified 'event' (Level C listeners).
boolean	isListening(java.lang.Class<?> eventClass, IWorldEventListener<?> listener) Tests whether the 'listener' is listening to a specific event (Level A listeners).
boolean	isListening(java.lang.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, java.lang.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(java.lang.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(java.lang.Class<?> objectClass, java.lang.Class<?> eventClass, IWorldObjectEventListener<?,?> listener) Removes listener from specific 'objectClass' listening for specified 'event' (Level C listeners).
void	removeObjectListener(java.lang.Class<?> objectClass, IWorldObjectEventListener<?,?> listener) Removes listener from specific 'objectClass' listening for specified 'event' (Level B listeners).
void	removeObjectListener(WorldObjectId objectId, java.lang.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).

Methods inherited from interface cz.cuni.amis.pogamut.base.communication.worldview.IWorldChangeEventInput

notify, notifyImmediately

Methods inherited from interface cz.cuni.amis.pogamut.base.component.IComponent

getComponentId

Method Detail

getEventBus

IComponentBus getEventBus()

addEventListener

void addEventListener(java.lang.Class<?> eventClass,
                      IWorldEventListener<?> listener)

Adds listener to a specific event (Level A listeners). Note that the event listener must be able to handle events of the class 'event'.

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'.

Parameters:

eventClass - which event types you want to receive

listener - where you want to handle these events

addObjectListener

void addObjectListener(java.lang.Class<?> objectClass,
                       IWorldObjectEventListener<?,?> listener)

Adds listener to all events that happens on any object of the 'objectClass' (Level B listeners).

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'.

Parameters:

objectClass - which object class you want to listen at

eventClass - which event class you want to receive

listener - where you want to handle these events

addObjectListener

void addObjectListener(java.lang.Class<?> objectClass,
                       java.lang.Class<?> eventClass,
                       IWorldObjectEventListener<?,?> listener)

Adds listener to a specified 'event' that occurs on the specific 'objectClass' (Level C listeners).

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.

Parameters:

objectClass - which object class you want to listen at

eventClass - which event class you want to receive

listener - where you want to handle these events

addObjectListener

void addObjectListener(WorldObjectId objectId,
                       IWorldObjectEventListener<?,?> listener)

Adds listener to all events that happens on object with specific 'objectId' (Level D listeners).

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'.

Parameters:

objectId - which object you want to listen at

listener - where you want to handle events

addObjectListener

void addObjectListener(WorldObjectId objectId,
                       java.lang.Class<?> eventClass,
                       IWorldObjectEventListener<?,?> listener)

Adds listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).

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'.

Parameters:

objectId - which object you want to listen at

eventClass - which event classes you want to receive

listener - where you want to handle these events

removeEventListener

void removeEventListener(java.lang.Class<?> eventClass,
                         IWorldEventListener<?> listener)

Removes listener from a specific event (Level A listeners).

Parameters:

eventClass - which events class you want to remove the listener from

listener - you want to remove

removeObjectListener

void removeObjectListener(java.lang.Class<?> objectClass,
                          IWorldObjectEventListener<?,?> listener)

Removes listener from specific 'objectClass' listening for specified 'event' (Level B listeners).

Parameters:

objectClass - class of objects you want the listener to remove from

eventClass - which events class you want to remove the listener from

listener - you want to remove

removeObjectListener

void removeObjectListener(java.lang.Class<?> objectClass,
                          java.lang.Class<?> eventClass,
                          IWorldObjectEventListener<?,?> listener)

Removes listener from specific 'objectClass' listening for specified 'event' (Level C listeners).

Parameters:

objectClass - class of objects you want the listener to remove from

eventClass - which events class you want to remove the listener from

listener - you want to remove

removeObjectListener

void removeObjectListener(WorldObjectId objectId,
                          IWorldObjectEventListener<?,?> listener)

Removes listener from objects with specified 'objectId' (Level D Listeners).

Parameters:

objectId - id of object you want the listener to remove from

listener - you want to remove

removeObjectListener

void removeObjectListener(WorldObjectId objectId,
                          java.lang.Class<?> eventClass,
                          IWorldObjectEventListener<?,?> listener)

Removes listener to a specified 'event' that occurs on the specific object with 'objectId' (Level E listeners).

Parameters:

objectId - id of object you want the listener to remove from

eventClass - event class you want to stop receiving in the listener

listener - you want to remove

removeListener

void removeListener(IWorldEventListener<?> listener)

Removes listener from every listeners category (from every listener level).

WARNING: Can be time consuming! (Iterating through all levels of listeners.)

Parameters:

listener - you want to remove from all listener levels

isListening

boolean isListening(java.lang.Class<?> eventClass,
                    IWorldEventListener<?> listener)

Tests whether the 'listener' is listening to a specific event (Level A listeners).

Parameters:

eventClass - which events you want to receive

listener - that is tested

Returns:

whether the listener is listening

isListening

boolean isListening(java.lang.Class<?> objectClass,
                    IWorldObjectEventListener<?,?> listener)

Tests whether the 'listener' is listening at specified 'objectClass' (Level B listeners).

Parameters:

objectClass - where the listener is tested

listener - that is tested

Returns:

whether the listener is listening

isListening

boolean isListening(java.lang.Class<?> objectClass,
                    java.lang.Class<?> eventClass,
                    IWorldObjectEventListener<?,?> listener)

Tests whether the 'listener' is listening at specified 'objectClass' for specified 'event' (Level C listeners).

Parameters:

objectClass - where the listener is tested

eventClass - where the listener is tested

listener - that is tested

Returns:

whether the listener is listening

isListening

boolean isListening(WorldObjectId objectId,
                    IWorldObjectEventListener<?,?> listener)

Tests whether the 'listener' is listening at specified 'objectId' (Level D Listeners).

Parameters:

objectId - where the listener is tested

listener - that is tested

Returns:

whether the listener is listening

isListening

boolean isListening(WorldObjectId objectId,
                    java.lang.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).

Parameters:

objectId - where the listener is tested

eventClass - what class is tested

listener - that is tested

Returns:

whether the listener is listening

isListening

boolean isListening(IWorldEventListener<?> listener)

Checks whether this listener is hooked to the world view (at any listener level).

WARNING: Can be time consuming! (Iterating through all levels of listeners.)

Parameters:

listener -

Returns:

getAll

java.util.Map<java.lang.Class,java.util.Map<WorldObjectId,IWorldObject>> getAll()

Returns map of all objects that are present in the world view.

WARNING: If you will do iteration over the map, you must synchronize on it.

getAll

<T extends IWorldObject> java.util.Map<WorldObjectId,T> getAll(java.lang.Class<T> type)

Returns map of all objects of a specific type that are present in the world view.

WARNING: If you will do iteration over the map, you must synchronize on it.

Parameters:

type -

Returns:

getSingle

<T extends IWorldObject> T getSingle(java.lang.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.

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".

Type Parameters:

T -

Parameters:

cls - Class of object to be retrieved

Returns:

the only object of given class

get

java.util.Map<WorldObjectId,IWorldObject> get()

Returns map with objects inserted according to their id.

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.

Returns:

get

IWorldObject get(WorldObjectId id)

Returns a world object of the specific id (if exists inside the world view). Otherwise, null is returned.

Note that there is no way to tell the correct type of returned object - you have to cast it to a correct class yourself.

Parameters:

id - objects's id

Returns: