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

Package class diagram package 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.

Author:
Jimmy

Method Summary
 void addEventListener(Class<?> event, Class<?> component, IComponentEventListener<?> listener)
          Attach listener to all events of class 'event' that is produced by any component of class 'component'.
 void addEventListener(Class<?> event, IComponentEventListener<?> listener)
          Attach listener to all events of class 'event'.
 void addEventListener(Class<?> event, IComponent component, IComponentEventListener<?> listener)
          Attach listener to all events of class 'event' that is produced by the 'component'.
 void addEventListener(Class<?> event, cz.cuni.amis.utils.token.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(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(cz.cuni.amis.utils.token.IToken componentId)
          Returns registered component of 'componentId'.
<T> Set<T>
getComponents(Class<T> cls)
          Return all registered components that descend from / implement class 'cls'.
 boolean isListening(Class<?> event, Class<?> component, IComponentEventListener<?> listener)
          Tests whether 'listener' is listening on events of class 'event' on components of class 'component'.
 boolean isListening(Class<?> event, IComponentEventListener<?> listener)
          Tests whether 'listener' is listening on events of class 'class'.
 boolean isListening(Class<?> event, IComponent component, IComponentEventListener<?> listener)
          Tests whether 'listener' is listening on events of class 'event' on the 'component'.
 boolean isListening(Class<?> event, cz.cuni.amis.utils.token.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(Class<?> event, Class<?> component, IComponentEventListener<?> listener)
          Removes 'listener' from event 'event' on component 'component'.
 void removeEventListener(Class<?> event, IComponentEventListener<?> listener)
          Removes 'listener' from event 'event'.
 void removeEventListener(Class<?> event, IComponent component, IComponentEventListener<?> listener)
          Removes 'listener' from event 'event' on the 'component'.
 void removeEventListener(Class<?> event, cz.cuni.amis.utils.token.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(cz.cuni.amis.utils.token.IToken componentId)
Returns registered component of 'componentId'.

Returns null if no such component exists.

Parameters:
componentId -
Returns:

getComponent

<T> T getComponent(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> Set<T> getComponents(Class<T> cls)
Return all registered components that descend from / implement class 'cls'.

Parameters:
cls -
Returns:

addEventListener

void addEventListener(Class<?> event,
                      IComponentEventListener<?> listener)
Attach listener to all events of class 'event'.

Parameters:
event -
listener -

addEventListener

void addEventListener(Class<?> event,
                      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(Class<?> event,
                      cz.cuni.amis.utils.token.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(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(Class<?> event,
                    IComponentEventListener<?> listener)
Tests whether 'listener' is listening on events of class 'class'.

Parameters:
event -
listener -
Returns:

isListening

boolean isListening(Class<?> event,
                    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(Class<?> event,
                    cz.cuni.amis.utils.token.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(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(Class<?> event,
                         IComponentEventListener<?> listener)
Removes 'listener' from event 'event'.

Parameters:
event -
listener -

removeEventListener

void removeEventListener(Class<?> event,
                         Class<?> component,
                         IComponentEventListener<?> listener)
Removes 'listener' from event 'event' on component 'component'.

Parameters:
event -
component -
listener -

removeEventListener

void removeEventListener(Class<?> event,
                         cz.cuni.amis.utils.token.IToken componentName,
                         IComponentEventListener<?> listener)
Removes 'listener' from event 'event' on component of name 'componentName'.

Parameters:
event -
componentName -
listener -

removeEventListener

void removeEventListener(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).


Copyright © 2015 AMIS research group, Faculty of Mathematics and Physics, Charles University in Prague, Czech Republic. All Rights Reserved.