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

java.lang.Object
  extended by 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