cz.cuni.amis.pogamut.base.component.bus
Interface IComponentBus

All Superinterfaces:

IComponent

All Known Subinterfaces:

ILifecycleBus

All Known Implementing Classes:

ComponentBus, LifecycleBus

public interface IComponentBus
extends IComponent

Component bus is meant as "event bus". Every agent will have exactly one component bus that serves as general-purpose event propagation bus.

Component bus stops its work when IFatalErrorEvent is passed to the component bus or an exception is thrown by any listener.

Every component that uses the bus should register at least one listener - listener for IFatalErrorEvent events as it is something as "global exception". Whenever the component is notified about the fatal error, it should stop its work.

Also - whenever the component catches an exception that it can't handle, it is bound to raise IFatalErrorEvent to notify the system that it is failing. If the component is not a critical piece of the puzzle, it may raise different event.

Method Summary

void	addEventListener(java.lang.Class<?> event, java.lang.Class<?> component, IComponentEventListener<?> listener) Attach listener to all events of class 'event' that is produced by any component of class 'component'.
void	addEventListener(java.lang.Class<?> event, IComponentEventListener<?> listener) Attach listener to all events of class 'event'.
void	addEventListener(java.lang.Class<?> event, IComponent component, IComponentEventListener<?> listener) Attach listener to all events of class 'event' that is produced by the 'component'.
void	addEventListener(java.lang.Class<?> event, IToken componentName, IComponentEventListener<?> listener) Attach listener to all events of class 'event' that is produced by \component with name 'componentName'.
boolean	event(IComponentEvent<?> event) Propagates new event.
void	eventTransactional(IComponentEvent<?> event) Propagates new event in the context of current event (if called within the context of event).
<T> T	getComponent(java.lang.Class<T> cls) Returns component of class 'cls', if there is more then one component for that class than an exception is thrown.
IComponent	getComponent(IToken componentId) Returns registered component of 'componentId'.
<T> java.util.Set<T>	getComponents(java.lang.Class<T> cls) Return all registered components that descend from / implement class 'cls'.
boolean	isListening(java.lang.Class<?> event, java.lang.Class<?> component, IComponentEventListener<?> listener) Tests whether 'listener' is listening on events of class 'event' on components of class 'component'.
boolean	isListening(java.lang.Class<?> event, IComponentEventListener<?> listener) Tests whether 'listener' is listening on events of class 'class'.
boolean	isListening(java.lang.Class<?> event, IComponent component, IComponentEventListener<?> listener) Tests whether 'listener' is listening on events of class 'event' on the 'component'.
boolean	isListening(java.lang.Class<?> event, IToken componentName, IComponentEventListener<?> listener) Tests whether 'listener' is listening on events of class 'event' on component of name 'componentName'.
boolean	isRunning() Whether the bus is propagating events.
void	register(IComponent component) Registers component into the bus.
void	remove(IComponent component) Removes component from the bus.
void	removeEventListener(java.lang.Class<?> event, java.lang.Class<?> component, IComponentEventListener<?> listener) Removes 'listener' from event 'event' on component 'component'.
void	removeEventListener(java.lang.Class<?> event, IComponentEventListener<?> listener) Removes 'listener' from event 'event'.
void	removeEventListener(java.lang.Class<?> event, IComponent component, IComponentEventListener<?> listener) Removes 'listener' from event 'event' on the 'component'.
void	removeEventListener(java.lang.Class<?> event, IToken componentName, IComponentEventListener<?> listener) Removes 'listener' from event 'event' on component of name 'componentName'.
void	reset() Restarts the bus and the whole agent system.

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

getComponentId

Method Detail

isRunning

boolean isRunning()

Whether the bus is propagating events.

Whenever IFatalErrorEvent is caught - the component bus will stop working immediately and propagate the fatal error as the last event (so if you will receive IFatalErrorEvent inside your object then it is pointless to send more events to the bus.

The only way to make the bus working is to reset() it.

Use this method to examine whether IFatalErrorEvent occured on the bus (and was broadcast) or not.

Returns:

reset

void reset()
           throws ResetFailedException

Restarts the bus and the whole agent system.

Broadcasts IResetEvent event. All components should stop working upon reset event and reinitialize their inner data structures into the initial state. If reset is not possible, the component should throw an exception.

If exception is caught during the reset(), the IFatalErrorEvent is propagated and the component bus won't start.

If reset() is called, when the component bus is still running, it first broadcasts IFatalErrorEvent.

Note that you can't propagate any events during the reset (they will be discarded).

Throws:

ResetFailedException - thrown when an exception happens during reset operation, nested exception is available through Throwable.getCause()

register

void register(IComponent component)
              throws ComponentIdClashException

Registers component into the bus.

If different component with the same IComponent.getComponentId() is already registered, than it throws ComponentIdClashException and broadcast IFatalErrorEvent.

Parameters:

component -

Throws:

ComponentIdClashException

remove

void remove(IComponent component)

Removes component from the bus.

Parameters:

component -

getComponent

IComponent getComponent(IToken componentId)

Returns registered component of 'componentId'.

Returns null if no such component exists.

Parameters:

componentId -

Returns:

getComponent

<T> T getComponent(java.lang.Class<T> cls)
               throws MoreComponentsForClassException

Returns component of class 'cls', if there is more then one component for that class than an exception is thrown.

If no components exist for 'cls', returns empty set.

Type Parameters:

T -

Parameters:

cls -

Returns:

Throws:

MoreComponentsForClassException

getComponents

<T> java.util.Set<T> getComponents(java.lang.Class<T> cls)

Return all registered components that descend from / implement class 'cls'.

Parameters:

cls -

Returns:

addEventListener

void addEventListener(java.lang.Class<?> event,
                      IComponentEventListener<?> listener)

Attach listener to all events of class 'event'.

Parameters:

event -

listener -

addEventListener

void addEventListener(java.lang.Class<?> event,
                      java.lang.Class<?> component,
                      IComponentEventListener<?> listener)

Attach listener to all events of class 'event' that is produced by any component of class 'component'.

Parameters:

event -

component -

listener -

addEventListener

void addEventListener(java.lang.Class<?> event,
                      IToken componentName,
                      IComponentEventListener<?> listener)

Attach listener to all events of class 'event' that is produced by \component with name 'componentName'.

Note that every component should have unique ID in the context of component bus instance.

Parameters:

event -

componentName -

listener -

addEventListener

void addEventListener(java.lang.Class<?> event,
                      IComponent component,
                      IComponentEventListener<?> listener)

Attach listener to all events of class 'event' that is produced by the 'component'.

Note that every component should have unique ID in the context of component bus instance.

Parameters:

event -

component -

listener -

isListening

boolean isListening(java.lang.Class<?> event,
                    IComponentEventListener<?> listener)

Tests whether 'listener' is listening on events of class 'class'.

Parameters:

event -

listener -

Returns:

isListening

boolean isListening(java.lang.Class<?> event,
                    java.lang.Class<?> component,
                    IComponentEventListener<?> listener)

Tests whether 'listener' is listening on events of class 'event' on components of class 'component'.

Parameters:

event -

component -

listener -

isListening

boolean isListening(java.lang.Class<?> event,
                    IToken componentName,
                    IComponentEventListener<?> listener)

Tests whether 'listener' is listening on events of class 'event' on component of name 'componentName'.

Parameters:

event -

componentName -

listener -

Returns:

isListening

boolean isListening(java.lang.Class<?> event,
                    IComponent component,
                    IComponentEventListener<?> listener)

Tests whether 'listener' is listening on events of class 'event' on the 'component'.

Parameters:

event -

component -

listener -

Returns:

removeEventListener

void removeEventListener(java.lang.Class<?> event,
                         IComponentEventListener<?> listener)

Removes 'listener' from event 'event'.

Parameters:

event -

listener -

removeEventListener

void removeEventListener(java.lang.Class<?> event,
                         java.lang.Class<?> component,
                         IComponentEventListener<?> listener)

Removes 'listener' from event 'event' on component 'component'.

Parameters:

event -

component -

listener -

removeEventListener

void removeEventListener(java.lang.Class<?> event,
                         IToken componentName,
                         IComponentEventListener<?> listener)

Removes 'listener' from event 'event' on component of name 'componentName'.

Parameters:

event -

componentName -

listener -

removeEventListener

void removeEventListener(java.lang.Class<?> event,
                         IComponent component,
                         IComponentEventListener<?> listener)

Removes 'listener' from event 'event' on the 'component'.

Parameters:

event -

component -

listener -

event

boolean event(IComponentEvent<?> event)
              throws ComponentBusNotRunningException,
                     ComponentBusErrorException,
                     FatalErrorPropagatingEventException

Propagates new event.

If this event is produced as an answer to other event (that is in the context of the listener call), than the event will be propagated after all listeners reacting to current event finishes. That is - the event will be postponed.

Can't be used to propagate IResetEvent.

Parameters:

event -

whether - the event has been processed or it has been added to the queue for the future invocation

Returns:

whether the event has been propagated

Throws:

ComponentBusNotRunningException - thrown when the bus is not running

ComponentBusErrorException - bus exception (report to authors)

FatalErrorPropagatingEventException - thrown when some listener throws an exception during the event propagation (use Throwable.getCause() to get the original exception).'

eventTransactional

void eventTransactional(IComponentEvent<?> event)
                        throws ComponentBusNotRunningException,
                               ComponentBusErrorException,
                               FatalErrorPropagatingEventException

Propagates new event in the context of current event (if called within the context of event).

If this method is called from in the context of some listener - then the event will be immediately propagate (unless some other eventTransactional() call is made). It allows you to create chain of events that create something like "transaction". If exception is thrown during this process, every listener will be notified about that and may act accordingly.

Note that if this method is not called in the context of listener then it will be postponed as if event() method is called.

Can't be used to propagate IResetEvent.

Parameters:

event -

Throws:

ComponentBusNotRunningException - thrown when the bus is not running

ComponentBusErrorException - whenever an exception happened during the propagation of the event (wrapped exception is accessible under Throwable.getCause())

FatalErrorPropagatingEventException - thrown when some listener throws an exception during the event propagation (use Throwable.getCause() to get the original exception).