org.lsst.ccs.services

Class AgentStateService

java.lang.Object

org.lsst.ccs.services.AgentStateService

All Implemented Interfaces:

BusMessagePreProcessor, ServiceLifecycle, AgentService

public final class AgentStateService
extends Object
implements AgentService, ServiceLifecycle, BusMessagePreProcessor

An AgentService to manage the internal state of an Agent.

Author:

The LSST CCS Team

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	AgentStateService.AgentStateServiceCommands

Constructor Summary

Constructors

Constructor and Description
AgentStateService()

Method Summary

Modifier and Type	Method and Description
void	addStateChangeListener(StateChangeListener stateChangeListener, Class... states)
String	getAgentServiceName() Get the name of this service.
Bus	getBus() The Bus this BusMessagePreProcessor applies to.
Enum	getComponentState(String component, Class stateClass) Returns the state of this Agent's component for the provided class.
StateBundle	getState() Returns a clone of the current Agent state.
Enum	getState(Class stateClass) Returns the state of this Agent for the provided class.
Object	getStateLock() Returns the object whose monitor lock guards write-access to the agent state.
boolean	isComponentInState(String component, Enum state) Check if a component of this Agent is in the given state.
boolean	isInState(Enum state) Check if this Agent is in the given state.
boolean	isInState(StateBundle state) Checks if this Agent is in all of the states contained in the given StateBundle.
void	preBuild()
void	preInit()
BusMessage	preProcessMessage(BusMessage msg) Pre-process the incoming BusMessage and return the message to be forwarded to the bus message listeners.
void	preShutdown()
void	preStart() Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#start() has been called.
<T extends Enum<T>> void	registerState(Class<T> state, String description, Object obj) Register a State with the AgentStateService.
void	removeStateChangeListener(StateChangeListener stateChangeListener)
boolean	startForAgent(AgentInfo agentInfo) This method is invoked after an agent service is created to see if this service is to be started for the tiven Agent.
void	updateAgentComponentState(org.lsst.ccs.utilities.taitime.CCSTimeStamp stateTransitionTimestamp, Object component, Enum... stateChanges) Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses.
void	updateAgentComponentState(Object component, Enum... stateChanges) Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses.
void	updateAgentState(org.lsst.ccs.utilities.taitime.CCSTimeStamp stateTransitionTimestamp, Enum... stateChanges) Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses.
void	updateAgentState(org.lsst.ccs.utilities.taitime.CCSTimeStamp stateTransitionTimestamp, StateBundle stateChanges) Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses.
void	updateAgentState(Enum... stateChanges) Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses.
void	updateAgentState(StateBundle stateChanges) Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses.
void	updateInternalState(AgentState... stateChanges) Updates the internal state of this Agent and publishes StateChangeNotification message.
boolean	waitFor(Predicate<StateBundle> target, long timeout, TimeUnit unit) Block until this Agent is in state that satisfies the specified predicate.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.lsst.ccs.ServiceLifecycle

afterInit, afterStart

Constructor Detail

AgentStateService

public AgentStateService()

Method Detail

getAgentServiceName

public String getAgentServiceName()

Description copied from interface: AgentService

Get the name of this service. This name will be used to add the given service to the lookup tree.

Specified by:

getAgentServiceName in interface AgentService

Returns:

the AgentService name.

startForAgent

public boolean startForAgent(AgentInfo agentInfo)

Description copied from interface: AgentService

This method is invoked after an agent service is created to see if this service is to be started for the tiven Agent.

Specified by:

startForAgent in interface AgentService

Returns:

true if the service is to be added to the given agent.

preStart

public void preStart()

Description copied from interface: ServiceLifecycle

Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#start() has been called.

The preceding lifecycle step is HasLifecycle.postInit()

The following lifecycle step is HasLifecycle.start() At the time it is called :

• the PhaseState is INITIALIZING
• connection with the messaging layer is effective, the enclosing subsystem has started StatusHeartBeat publication

Specified by:

preStart in interface ServiceLifecycle

preShutdown

public void preShutdown()

Specified by:

preShutdown in interface ServiceLifecycle

preBuild

public void preBuild()

Specified by:

preBuild in interface ServiceLifecycle

preInit

public void preInit()

Specified by:

preInit in interface ServiceLifecycle

registerState

public final <T extends Enum<T>> void registerState(Class<T> state,
                                                    String description,
                                                    Object obj)

Register a State with the AgentStateService. Only registered states can be set on the Agent state. This registration step is only required for WORKERS.

Type Parameters:

T -

Parameters:

state - The State Enumeration Class to be registered

description - The state description

obj - The object on which the state will be set.

getStateLock

public Object getStateLock()

Returns the object whose monitor lock guards write-access to the agent state. The state is guaranteed to remain unchanged while this lock is held.

Returns:

the inner state lock to perform synchronized operations on states.

isInState

public boolean isInState(Enum state)

Check if this Agent is in the given state.

Parameters:

state - The state to check.

Returns:

true if this Agent is in the specified state.

isComponentInState

public boolean isComponentInState(String component,
                                  Enum state)

Check if a component of this Agent is in the given state.

Parameters:

component - The name of the component

state - The state to check.

Returns:

true if this Agent's component is in the specified state.

isInState

public boolean isInState(StateBundle state)

Checks if this Agent is in all of the states contained in the given StateBundle.

Parameters:

state - A StateBundle.

Returns:

true if the Agent is in the provided StateBundle.

getState

public Enum getState(Class stateClass)

Returns the state of this Agent for the provided class.

Parameters:

stateClass - The class of the Enum for which we would like the Agent's state.

Returns:

state for the specified class.

getComponentState

public Enum getComponentState(String component,
                              Class stateClass)

Returns the state of this Agent's component for the provided class.

Parameters:

component - The Agent's component name

stateClass - The class of the Enum for which we would like the Agent's state.

Returns:

The component's state for the specified class.

updateAgentState

public void updateAgentState(Enum... stateChanges)

Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses. Note that this method should be used to modify subsystem-defined states only. Internal Agent states (AlertState, CommandState, OperationalState, PhaseState) are managed by the Agent. This method will produce a StatusStateChangeNotification to be published on the buses only if there are state changes. This method can be invoked at any stage of HasLifecycle When this method is invoked the CCSTimeStamp.currentTime() is assigned to the state transition.

Parameters:

stateChanges - The list of the states that have changed.

Throws:

IllegalArgumentException - if the list of arguments contains internal Agent states.

updateAgentState

public void updateAgentState(org.lsst.ccs.utilities.taitime.CCSTimeStamp stateTransitionTimestamp,
                             Enum... stateChanges)

Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses. The provided CCSTimeStamp is associated to the state transition. Note that this method should be used to modify subsystem-defined states only. Internal Agent states (AlertState, CommandState, OperationalState, PhaseState) are managed by the Agent. This method will produce a StatusStateChangeNotification to be published on the buses only if there are state changes. This method can be invoked at any stage of HasLifecycle

Parameters:

stateTransitionTimestamp - The CCSTimeStamp corresponding to this state transition

stateChanges - The list of the states that have changed.

Throws:

IllegalArgumentException - if the list of arguments contains internal Agent states.

updateAgentState

public void updateAgentState(StateBundle stateChanges)

Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses. Note that this method should be used to modify subsystem-defined states only. Internal Agent states (AlertState, CommandState, OperationalState, PhaseState) are managed by the Agent. This method will produce a StatusStateChangeNotification to be published on the buses only if there are state changes. This method can be invoked at any stage of HasLifecycle When this method is invoked the CCSTimeStamp.currentTime() is assigned to the state transition.

Parameters:

stateChanges - The StateBundle with all the changes.

Throws:

IllegalArgumentException - if the list of arguments contains internal Agent states.

updateAgentState

public void updateAgentState(org.lsst.ccs.utilities.taitime.CCSTimeStamp stateTransitionTimestamp,
                             StateBundle stateChanges)

Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses. The provided CCSTimeStamp is associated to the state transition. Note that this method should be used to modify subsystem-defined states only. Internal Agent states (AlertState, CommandState, OperationalState, PhaseState) are managed by the Agent. This method will produce a StatusStateChangeNotification to be published on the buses only if there are state changes. This method can be invoked at any stage of HasLifecycle

Parameters:

stateTransitionTimestamp - The CCSTimeStamp corresponding to this state transition

stateChanges - The StateBundle with all the changes.

Throws:

IllegalArgumentException - if the list of arguments contains internal Agent states.

updateAgentComponentState

public void updateAgentComponentState(Object component,
                                      Enum... stateChanges)

Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses. Note that this method should be used to modify subsystem-defined states only. Internal Agent states (AlertState, CommandState, OperationalState, PhaseState) are managed by the Agent. This method will produce a StatusStateChangeNotification to be published on the buses only if there are state changes. When this method is invoked the CCSTimeStamp.currentTime() is assigned to the state transition. This method can be invoked at any stage of HasLifecycle

Parameters:

component - The name of the component to be updated

stateChanges - The list of the states that have changed.

Throws:

IllegalArgumentException - if the list of arguments contains internal Agent states.

updateAgentComponentState

public void updateAgentComponentState(org.lsst.ccs.utilities.taitime.CCSTimeStamp stateTransitionTimestamp,
                                      Object component,
                                      Enum... stateChanges)

Updates the state of this Agent and publishes StateChangeNotification message only if the Agent is connected to the buses. The provided CCSTimeStamp is associated to the state transition. Note that this method should be used to modify subsystem-defined states only. Internal Agent states (AlertState, CommandState, OperationalState, PhaseState) are managed by the Agent. This method will produce a StatusStateChangeNotification to be published on the buses only if there are state changes. This method can be invoked at any stage of HasLifecycle

Parameters:

stateTransitionTimestamp - The CCSTimeStamp corresponding to this state transition

component - The name of the component to be updated

stateChanges - The list of the states that have changed.

Throws:

IllegalArgumentException - if the list of arguments contains internal Agent states.

updateInternalState

public final void updateInternalState(AgentState... stateChanges)

Updates the internal state of this Agent and publishes StateChangeNotification message.

Parameters:

stateChanges - The list of the states that have changed.

Throws:

IllegalArgumentException - if the update would bring this Agent into a prohibited state

waitFor

public final boolean waitFor(Predicate<StateBundle> target,
                             long timeout,
                             TimeUnit unit)
                      throws InterruptedException

Block until this Agent is in state that satisfies the specified predicate. The condition is not guaranteed to remain true when the thread resumes. The predicate provided to this method should not depend on anything other than its argument, and should not have side effects.

Parameters:

target - Condition to be satisfied for this method to return.

timeout - Timeout value.

unit - Timeout unit.

Returns:

True if the condition was satisfied; false if the method timed out.

Throws:

InterruptedException - if the thread is interrupted while waiting.

addStateChangeListener

public void addStateChangeListener(StateChangeListener stateChangeListener,
                                   Class... states)

removeStateChangeListener

public void removeStateChangeListener(StateChangeListener stateChangeListener)

getState

public StateBundle getState()

Returns a clone of the current Agent state. The returned object is a snapshot of the current state. It is not modified by subsequent changes to the agent state.

Returns:

A clone of the current Agent state.

preProcessMessage

public BusMessage preProcessMessage(BusMessage msg)

Description copied from interface: BusMessagePreProcessor

Pre-process the incoming BusMessage and return the message to be forwarded to the bus message listeners. The returned message can either be a modified version of the original message or a brand new message. The Class of the returned message can be different than the incoming message. If null is returned the message will not be sent to the BusMessage listeners, but it will still be passed to other BusMessagePreProcessors This method can be invoked by separate threads, but it's invoked by one thread at a time; there is no concurrent invocation of the method.

Specified by:

preProcessMessage in interface BusMessagePreProcessor

Parameters:

msg - The incoming BusMessage

Returns:

The modified BusMessage to be forwarded to the BusMessageListeners

getBus

public Bus getBus()

Description copied from interface: BusMessagePreProcessor

The Bus this BusMessagePreProcessor applies to.

Specified by:

getBus in interface BusMessagePreProcessor

Returns:

The Bus.