cz.cuni.amis.pogamut.base.component.controller

Interface IComponentControllerBase<COMPONENT extends IComponent>

All Superinterfaces:

IComponent

All Known Subinterfaces:

IComponentController<COMPONENT>, ISharedComponentController<COMPONENT>

All Known Implementing Classes:

AbstractComponentControllerBase, ComponentController, SharedComponentController

public interface IComponentControllerBase<COMPONENT extends IComponent>
extends IComponent

Base interface for component controllers, be it IComponentController or ISharedComponentController.

The component controller base interface is meant to provide a gateway for starting/stopping/pausing/resuming the component and querying the component current ComponentState.

Use AbstractComponentControllerBase abstraction for the implementation of custom controllers.

Author:

Jimmy

Method Summary

Methods

Modifier and Type	Method and Description
ComponentState	awaitState(ComponentState... states) Waits until the component reaches one of 'states' or KILLING / KILLED state is reached.
ComponentState	awaitState(long timeoutMillis, ComponentState... states) Waits until the component reaches one of 'states' or KILLING / KILLED state is reached.
void	fatalError(String message) Broadcasts fatal error with controlled component as source.
void	fatalError(String message, Throwable e) Broadcasts fatal error with controlled component as source.
COMPONENT	getComponent() Returns controlled component instance.
IComponentControlHelper	getComponentControl() Returns component control with lifecycle methods of the component controlled by this instance.
IFatalErrorEvent	getFatalError() Returns last fatal error event that has triggered the system failure.
cz.cuni.amis.utils.flag.ImmutableFlag<ComponentState>	getState() Returns state of the controlled component (state of the component life-cycle).
boolean	inState(ComponentState... states) Whether the component is in one of 'states'.
boolean	isBroadcastingEvents() Tells whether the controller sends events about the state of the component, i.e., whether it should automatically send starting/stopping events or not.
boolean	isPaused() Whether the component is paused (or is pausing/resuming).
boolean	isRunning() Whether the component has been started, is not stopped or killed, may be paused.
void	manualKill(String reason) Provides the way to kill the component (constructor of this controller).
void	manualPause(String reason) Provides the way to pause the component (constructor of this controller).
void	manualResume(String reason) Provides the way to pause the component (constructor of this controller).
void	manualStart(String reason) Provides the way to manually start the component.
void	manualStartPaused(String reason) Provides the way to manually start the component into paused state.
void	manualStop(String reason) Provides the way to stop the component (constructor of this controller).
boolean	notInState(ComponentState... states) Whether the component is not in any of 'states'.
void	setBroadcastingEvents(boolean broadcastEvents) Enables (== true) / Disables (== false) sending events about the state of the component, i.e., whether it should automatically send starting/stopping events or not.

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

getComponentId

Method Detail

getFatalError

IFatalErrorEvent getFatalError()

Returns last fatal error event that has triggered the system failure.

isRunning

boolean isRunning()

Whether the component has been started, is not stopped or killed, may be paused.

Returns:

component is running

isPaused

boolean isPaused()

Whether the component is paused (or is pausing/resuming).

Returns:

getState

cz.cuni.amis.utils.flag.ImmutableFlag<ComponentState> getState()

Returns state of the controlled component (state of the component life-cycle).

It returns flag - therefore you may use WaitForFlagChange to synchronize on the flag changes in other threads or use awaitState() method.

Returns:

immutable flag

inState

boolean inState(ComponentState... states)

Whether the component is in one of 'states'.

Parameters:

states -

Returns:

notInState

boolean notInState(ComponentState... states)

Whether the component is not in any of 'states'.

Parameters:

states -

Returns:

awaitState

ComponentState awaitState(ComponentState... states)

Waits until the component reaches one of 'states' or KILLING / KILLED state is reached.

If KILLING / KILLED state is not among 'states' then reaching of this state will throw ComponentKilledException exception.

If interrupted, PogamutInterruptedException is thrown.

Parameters:

state -

Returns:

reached component state

Throws:

ComponentKilledException

awaitState

ComponentState awaitState(long timeoutMillis,
                        ComponentState... states)

Waits until the component reaches one of 'states' or KILLING / KILLED state is reached.

If KILLING / KILLED state is not among 'states' then reaching of this state will throw ComponentKilledException exception.

If interrupted, PogamutInterruptedException is thrown.

If times out, null is returned.

Parameters:

millis -

state -

Returns:

reached component state

Throws:

ComponentKilledException

manualStart

void manualStart(String reason)

Provides the way to manually start the component.

manualStartPaused

void manualStartPaused(String reason)

Provides the way to manually start the component into paused state.

manualStop

void manualStop(String reason)

Provides the way to stop the component (constructor of this controller).

Note that you should not use IComponentControlHelper.stop() alone to stop your component as it won't produce IStoppingEvent and IStoppedEvent.

If you require your component to stop prematurely - call this method.

Parameters:

reason - why the component is stopping

manualKill

void manualKill(String reason)

Provides the way to kill the component (constructor of this controller).

Note that you should not use IComponentControlHelper.kill() alone to stop your component as it won't produce IFatalErrorEvent.

If you require your component to stop prematurely - call this method.

Parameters:

reason - why the component is stopping

manualPause

void manualPause(String reason)

Provides the way to pause the component (constructor of this controller).

Note that you should not use IComponentControlHelper.pause() alone to stop your component as it won't produce IPausingEvent and IPausedEvent.

Parameters:

reason - why the component is pausing

manualResume

void manualResume(String reason)

Provides the way to pause the component (constructor of this controller).

Note that you should not use IComponentControlHelper.pause() alone to stop your component as it won't produce IPausingEvent and IPausedEvent.

Parameters:

reason - why the component is pausing

fatalError

void fatalError(String message)

Broadcasts fatal error with controlled component as source.

Sets state to KILLING, broadcasts IFatalErrorEvent and then sets the state to KILLED.

WARNING: Note that the ComponentController assumes that you will kill your component yourself before or after you call this method. Therefore the components kill() method won't be called. That's because whenever fatal error occurs, the component is in undefined state and you have to decide what to do based on that fatal error.

Parameters:

message -

fatalError

void fatalError(String message,
              Throwable e)

Broadcasts fatal error with controlled component as source.

Sets state to KILLING, broadcasts IFatalErrorEvent and then sets the state to KILLED.

WARNING: Note that the ComponentController assumes that you will kill your component yourself before or after you call this method. Therefore the components kill() method won't be called. That's because whenever fatal error occurs, the component is in undefined state and you have to decide what to do based on that fatal error.

Parameters:

message -

e -

getComponent

COMPONENT getComponent()

Returns controlled component instance.

Returns:

controlled component

getComponentControl

IComponentControlHelper getComponentControl()

Returns component control with lifecycle methods of the component controlled by this instance. I.e., methods that are directly controlling the component getComponent().

IT IS DISCOURAGED TO USE METHODS OF THE IComponentControlHelper DIRECTLY! IT DEFIES THE PURPOSE OF THE CONTROLLER TOTALLY AND THE CONTROLLER WILL PROBABLY WON'T COPE WITH SUCH BEHAVIOR.

But what the hell, if it solves your problem, go ahead ;-)

Returns:

isBroadcastingEvents

boolean isBroadcastingEvents()

Tells whether the controller sends events about the state of the component, i.e., whether it should automatically send starting/stopping events or not.

DEFAULT: TRUE (the controller is broadcasting events as default)

Exception: fatalError(String) and fatalError(String, Throwable) must always send fatal error!

Returns:

setBroadcastingEvents

void setBroadcastingEvents(boolean broadcastEvents)

Enables (== true) / Disables (== false) sending events about the state of the component, i.e., whether it should automatically send starting/stopping events or not.

Exception: fatalError(String) and fatalError(String, Throwable) must always send fatal error!

Parameters:

broadcastEvents - Enables (== true) / Disables (== false)