cz.cuni.amis.pogamut.base.component.lifecyclebus
Interface ILifecycleBus

All Superinterfaces:
IComponent, IComponentBus
All Known Implementing Classes:
LifecycleBus

public interface ILifecycleBus
extends IComponentBus

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

Additionally the class is providing the functionality of ComponentController offering components a helping hand to watch over events that are being broadcast over the bus and calls their lifecycle methods (IComponentControlHelper in correct times and according to their ComponentDependencies.

Additionally the LifecycleBus may accomodate ISharedComponents as we're providing lifecycle management here as well.


Method Summary
<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'.
 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'.
 void removeLifecycleManagement(IComponent component)
          Removes lifecycle management for a concrete 'component'.
 
Methods inherited from interface cz.cuni.amis.pogamut.base.component.bus.IComponentBus
addEventListener, addEventListener, addEventListener, addEventListener, event, eventTransactional, getComponent, getComponent, getComponents, isListening, isListening, isListening, isListening, isRunning, register, remove, removeEventListener, removeEventListener, removeEventListener, removeEventListener, reset
 
Methods inherited from interface cz.cuni.amis.pogamut.base.component.IComponent
getComponentId
 

Method Detail

getComponentState

ImmutableFlag<ComponentState> getComponentState(IToken componentId)
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.

Parameters:
componentId -
Returns:

getComponentState

ImmutableFlag<ComponentState> getComponentState(java.lang.Class<? extends IComponent> cls)
                                                throws MoreComponentsForClassException
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.

Type Parameters:
T -
Parameters:
cls -
Returns:
flag with the state of the component
Throws:
MoreComponentsForClassException

addLifecycleManagement

<T extends IComponent> IComponentController<T> addLifecycleManagement(T component,
                                                                      IComponentControlHelper lifecyleMethods,
                                                                      ComponentDependencies componentDependencies)
                                                                  throws ComponentLifecycleManagementAlreadyRegisteredException
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).

Parameters:
component -
lifecyleMethods -
componentDependencies -
Returns:
controller that is used for the control of the component inside this bus
Throws:
ComponentLifecycleManagementAlreadyRegisteredException

removeLifecycleManagement

void removeLifecycleManagement(IComponent component)
Removes lifecycle management for a concrete 'component'.

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

Parameters:
componentId -