cz.cuni.amis.pogamut.base.component.lifecyclebus
Class LifecycleBus

java.lang.Object
  cz.cuni.amis.pogamut.base.component.lifecyclebus.LifecycleBus

All Implemented Interfaces:

IComponentBus, IComponent, IComponentAware, ILifecycleBus

public class LifecycleBus
extends java.lang.Object
implements ILifecycleBus, IComponentAware

Lifecycle bus is implementing ILifecycleBus which is extending IComponentBus by implementing the knowledge of lifecycle states of various IComponents. It watches over the ComponentStates, providing information about them.

Too complex - not suitable for inheritance ... copy paste source code and change it manually ... as it was done for ComponentBus before.

For more documentation see IComponentBus.

For more documentation regarding lifecycle management, see ComponentController as LifecycleBus is working the same way.

Field Summary

static IToken

COMPONENT_ID

Constructor Summary

LifecycleBus(IAgentLogger logger)

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'.
<T extends IComponent> IComponentController<T>	addLifecycleManagement(T component, IComponentControlHelper lifecyleMethods, ComponentDependencies componentDependencies) Registers 'lifecycleMethods' to be called in correct times according to 'componentDependencies' for the 'component'.
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 name) Returns registered component of 'componentId'.
IToken	getComponentId() Unique identification of the component.
<T> java.util.Set<T>	getComponents(java.lang.Class<T> cls) Return all registered components that descend from / implement class 'cls'.
ImmutableFlag<ComponentState>	getComponentState(java.lang.Class<? extends IComponent> cls) Returns current ComponentState of the component that implements / inherit the 'cls' class.
ImmutableFlag<ComponentState>	getComponentState(IToken componentId) Returns current ComponentState of the component identified by 'componentId'.
IComponentBus	getEventBus() IComponentBus that the instance is working with.
java.util.logging.Logger	getLog()
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 componentId, 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 componentId, IComponentEventListener<?> listener) Removes 'listener' from event 'event' on component of name 'componentName'.
void	removeLifecycleManagement(IComponent component) Removes lifecycle management for a concrete 'component'.
void	reset() Restarts the bus and the whole agent system.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

COMPONENT_ID

public static final IToken COMPONENT_ID

Constructor Detail

LifecycleBus

@Inject
public LifecycleBus(IAgentLogger logger)

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getEventBus

public IComponentBus getEventBus()

Description copied from interface: IComponentAware

IComponentBus that the instance is working with.

Note that by design-choice - the IComponentBus is a singleton inside AgentScoped, therefore you don't have to necessarily obtain the instance through the component, it suffice to obtain it using injection into your object.

Specified by:

getEventBus in interface IComponentAware

Returns:

getComponentId

public IToken getComponentId()

Description copied from interface: IComponent

Unique identification of the component.

Specified by:

getComponentId in interface IComponent

Returns:

getLog

public java.util.logging.Logger getLog()

isRunning

public boolean isRunning()

Description copied from interface: IComponentBus

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.

Specified by:

isRunning in interface IComponentBus

Returns:

reset

public void reset()
           throws ResetFailedException

Description copied from interface: IComponentBus

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

Specified by:

reset in interface IComponentBus

Throws:

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

getComponent

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

Description copied from interface: IComponentBus

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.

Specified by:

getComponent in interface IComponentBus

Returns:

Throws:

MoreComponentsForClassException

getComponents

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

Description copied from interface: IComponentBus

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

Specified by:

getComponents in interface IComponentBus

Returns:

register

public void register(IComponent component)
              throws ComponentIdClashException

Description copied from interface: IComponentBus

Registers component into the bus.

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

Specified by:

register in interface IComponentBus

Throws:

ComponentIdClashException

remove

public void remove(IComponent component)

Description copied from interface: IComponentBus

Removes component from the bus.

Specified by:

remove in interface IComponentBus

getComponent

public IComponent getComponent(IToken name)

Description copied from interface: IComponentBus

Returns registered component of 'componentId'.

Returns null if no such component exists.

Specified by:

getComponent in interface IComponentBus

Returns:

addEventListener

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

Description copied from interface: IComponentBus

Attach listener to all events of class 'event'.

Specified by:

addEventListener in interface IComponentBus

addEventListener

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

Description copied from interface: IComponentBus

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

Specified by:

addEventListener in interface IComponentBus

addEventListener

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

Description copied from interface: IComponentBus

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.

Specified by:

addEventListener in interface IComponentBus

addEventListener

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

Description copied from interface: IComponentBus

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.

Specified by:

addEventListener in interface IComponentBus

isListening

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

Description copied from interface: IComponentBus

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

Specified by:

isListening in interface IComponentBus

Returns:

isListening

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

Description copied from interface: IComponentBus

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

Specified by:

isListening in interface IComponentBus

isListening

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

Description copied from interface: IComponentBus

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

Specified by:

isListening in interface IComponentBus

Returns:

isListening

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

Description copied from interface: IComponentBus

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

Specified by:

isListening in interface IComponentBus

Returns:

removeEventListener

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

Description copied from interface: IComponentBus

Removes 'listener' from event 'event'.

Specified by:

removeEventListener in interface IComponentBus

removeEventListener

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

Description copied from interface: IComponentBus

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

Specified by:

removeEventListener in interface IComponentBus

removeEventListener

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

Description copied from interface: IComponentBus

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

Specified by:

removeEventListener in interface IComponentBus

removeEventListener

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

Description copied from interface: IComponentBus

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

Specified by:

removeEventListener in interface IComponentBus

event

public boolean event(IComponentEvent event)
              throws ComponentBusNotRunningException,
                     ComponentBusErrorException,
                     FatalErrorPropagatingEventException

Description copied from interface: IComponentBus

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.

Specified by:

event in interface IComponentBus

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

public void eventTransactional(IComponentEvent event)
                        throws ComponentBusNotRunningException,
                               ComponentBusErrorException,
                               FatalErrorPropagatingEventException

Description copied from interface: IComponentBus

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.

Specified by:

eventTransactional in interface IComponentBus

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

addLifecycleManagement

public <T extends IComponent> IComponentController<T> addLifecycleManagement(T component,
                                                                             IComponentControlHelper lifecyleMethods,
                                                                             ComponentDependencies componentDependencies)
                                                                  throws ComponentLifecycleManagementAlreadyRegisteredException

Description copied from interface: ILifecycleBus

Registers 'lifecycleMethods' to be called in correct times according to 'componentDependencies' for the 'component'.

This method provides a powerful feature for IComponent to offload the troubles with sensing starting/stopping events of components it depends on in order to start/stop in correct times. It supplies the functionality of ComponentController which provides the same for simpler ComponentBus.

Every component may register only one lifecycle management.

The lifecycle management may be removed using IComponentBus.removeEventListener(Class, cz.cuni.amis.pogamut.base.component.bus.IComponentEventListener).

WARNING: the 'lifecycleMethods' object is hold via WeakReference, you must store it for yourself! It also means you must have to store the instance of your component somewhere in the strongly referenced part of your code (i.e., in the IAgent instance).

Specified by:

addLifecycleManagement in interface ILifecycleBus

Returns:

controller that is used for the control of the component inside this bus

Throws:

ComponentLifecycleManagementAlreadyRegisteredException

getComponentState

public ImmutableFlag<ComponentState> getComponentState(IToken componentId)

Description copied from interface: ILifecycleBus

Returns current ComponentState of the component identified by 'componentId'.

Note that nothing guarantees that the state will change afterwards.

Note that we're not returning mere ComponentState but the immutable flag that you may use to attach FlagListeners to it allowing you to react on its changes as they happen.

WARNING: ISharedComponent state is always reported from the point of view of the bus, not the component! That means that the ISharedComponent may mask its behavior as if it would be a simple IComponent owned by single agent. For instance, after the bus broadcast IFatalErrorEvent as it is believed that all components will be killed thus the lifecycle bus will switch the component state into "KILLED" and after reset to "RESETED". Moreover, such behavior is quite a desired one because otherwise it would add unnecessary complexity from the point of view of the single agent and management of component auto-starting feature provided by IComponentController.

Specified by:

getComponentState in interface ILifecycleBus

Returns:

getComponentState

public ImmutableFlag<ComponentState> getComponentState(java.lang.Class<? extends IComponent> cls)
                                                throws MoreComponentsForClassException

Description copied from interface: ILifecycleBus

Returns current ComponentState of the component that implements / inherit the 'cls' class.

Note that nothing guarantees that the state will change afterwards.

If no components exist for 'cls', returns null.

Raises an exception MoreComponentsForClassException if more components for 'cls' exists.

Note that we're not returning mere ComponentState but the immutable flag that you may use to attach FlagListeners to it allowing you to react on its changes as they happen.

WARNING: ISharedComponent state is always reported from the point of view of the bus, not the component! That means that the ISharedComponent may mask its behavior as if it would be a simple IComponent owned by single agent. For instance, after the bus broadcast IFatalErrorEvent as it is believed that all components will be killed thus the lifecycle bus will switch the component state into "KILLED" and after reset to "RESETED". Moreover, such behavior is quite a desired one because otherwise it would add unnecessary complexity from the point of view of the single agent and management of component auto-starting feature provided by IComponentController.

Specified by:

getComponentState in interface ILifecycleBus

Returns:

flag with the state of the component

Throws:

MoreComponentsForClassException

removeLifecycleManagement

public void removeLifecycleManagement(IComponent component)

Description copied from interface: ILifecycleBus

Removes lifecycle management for a concrete 'component'.

Does nothing if the component does not have life-cycle methods registered inside the bus.

Specified by:

removeLifecycleManagement in interface ILifecycleBus