org.lsst.ccs

Class Agent

java.lang.Object

org.lsst.ccs.Agent

All Implemented Interfaces:

CommandExecutor

Direct Known Subclasses:

Subsystem

public class Agent
extends Object
implements CommandExecutor

Minimal component able to communicate on the buses. The following functionality is supported by the Agent:

• Access to the buses through an instance of AgentMessagingLayer.
• A method for publishing arbitrary objects on the status bus.
• Protected methods for checking, modifying, and publishing the Agent state. Access to the state is synchronized so these methods can be called from any thread.
• Heartbeat publishing.
• Command processing.
• Scheduling periodic and delayed tasks.

Author:

emarin

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Agent.RunningCommand Represents a command accepted for execution by this Agent.

Field Summary

Fields

Modifier and Type	Field and Description
protected Object	commandExecutorLock Lock that guards command executor state.
protected Agent.RunningCommand	currentAction Currently running CONFIGURATION or ACTION command.
protected Set<Agent.RunningCommand>	currentQueries Currently running QUERY commands.
protected Set<Agent.RunningCommand>	currentSignals Currently running SIGNAL commands.
protected PeriodicTask	heartbeatPublisher Scheduler task that publishes heartbeat status messages.
protected Object	innerStateLock Lock for innerState variable.
protected LogBusHandler	logBusHandler Logging bus handler
protected PeriodicTask	runtimeInfoPublisher Scheduler task that publishes runtime info messages.

Constructor Summary

Constructors

Constructor and Description
Agent(String name, AgentInfo.AgentType agentType) Constructs an Agent.

Method Summary

Modifier and Type	Method and Description
protected void	addCommandSet(String name, CommandSet commandSet) Adds a CommandSet to extend the set of commands recognized by this Agent.
void	addCommandsFromObject(Object obj, String path) Add the commands defined in an Object to this Agent's CommandSet.
protected void	broadcastStatus() Broadcasts the current heartbeat status.
void	executeCommandRequest(CommandRequest request) Executes the received command
AgentInfo	getAgentInfo() Returns AgentIfno instance associated with this Agent.
CCSVersions	getCCSVersions() Command to get the CCSVersions object for the current CCS Environment.
int	getCommandCount(Command.CommandType... types) Returns the number of currently running commands of given types.
protected CommandSet	getCommandSet(String name)
List<String>	getCommandTargets() Returns this Agent list of command targets.
Agent.RunningCommand	getCurrentAction() Get the current RunningCommand action.
HashMap<String,Dictionary>	getDictionaries() Returns the command dictionary used by this Agent.
DistributionInfo	getDistributionInfo() Command to get the DistributionInfo object for this Agent.
static AgentMessagingLayer	getEnvironmentMessagingAccess() Deprecated.
AgentMessagingLayer	getMessagingAccess() Returns AgentMessagingLayer used by this Agent.
String	getName() Returns the name of this Agent.
Scheduler	getScheduler() Returns Scheduler used by this Agent.
StateBundle	getState() Returns a copy of a state bundle of this Agent.
Enum	getState(Class stateClass) Returns the state of this Agent for the provided class.
int	getStatusBroadcastPeriod() Returns heartbeat broadcasting period for this Agent.
protected void	internalShutdown() This method is called by the framework at the beginning of Agent shutdown, once the phase has been switched to OPERATIONAL.
protected boolean	internalStart() This method is called by the framework at the end of Agent startup, before switching to OPERATIONAL phase.
boolean	isInEngineeringMode() Command to tell if the subsystem is in Engineering mode.
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.
protected void	publishStateChange(String extraInfo, StateBundle before, StateBundle after) Publishes state transition.
void	publishSubsystemDataOnStatusBus(KeyValueData keyValueData) Publishes the provided KeyValueData on the Status bus.
boolean	sendAck(Duration timeout) Sends an ACK to the command originator.
boolean	sendNack(Serializable reason) Sends a NACK to the command originator.
void	setAgentProperty(String property, String value) Set an Agent property.
Object	shutdown() Clean shutdown of subsystem: call stop for hardware stopping before invoking this method.
void	start() Starts this Agent
void	updateAgentState(String extraInfo, Enum... stateChanges) Updates the state of this Agent and publishes StateChangeNotification message.
protected void	updateHeartBeat(StatusHeartBeat heartBeat) Subclasses can override this method to add customized information to the heartbeat.
protected void	updateInternalState(String extraInfo, 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

Field Detail

logBusHandler

protected LogBusHandler logBusHandler

Logging bus handler

commandExecutorLock

protected final Object commandExecutorLock

Lock that guards command executor state.

currentQueries

protected final Set<Agent.RunningCommand> currentQueries

Currently running QUERY commands.

currentAction

protected volatile Agent.RunningCommand currentAction

Currently running CONFIGURATION or ACTION command.

currentSignals

protected final Set<Agent.RunningCommand> currentSignals

Currently running SIGNAL commands.

innerStateLock

protected final Object innerStateLock

Lock for innerState variable.

heartbeatPublisher

protected final PeriodicTask heartbeatPublisher

Scheduler task that publishes heartbeat status messages.

runtimeInfoPublisher

protected final PeriodicTask runtimeInfoPublisher

Scheduler task that publishes runtime info messages.

Constructor Detail

Agent

public Agent(String name,
             AgentInfo.AgentType agentType)

Constructs an Agent.

Parameters:

name - name of this Agent; for CONSOLE and LISTENER agents, the name will be modified to ensure uniqueness.

agentType - type of this Agent.

Method Detail

start

public void start()

Starts this Agent

shutdown

@Command(description="shutdown",
         type=ACTION)
public final Object shutdown()
                                                                             throws Exception

Clean shutdown of subsystem: call stop for hardware stopping before invoking this method.

Returns:

Status of the shutdown

Throws:

Exception - If anything goes wrong during shutdown

internalStart

protected boolean internalStart()

This method is called by the framework at the end of Agent startup, before switching to OPERATIONAL phase. Subclasses can override it to implement their specific startup procedures. This class provides implementation that does nothing and returns true.

Returns:

True if the startup was successful, false otherwise.

internalShutdown

protected void internalShutdown()
                         throws Exception

This method is called by the framework at the beginning of Agent shutdown, once the phase has been switched to OPERATIONAL. Subclasses can override it to implement their specific shutdown procedures. If anything goes wrong an Exception should be thrown. This class provides an empty implementation.

Throws:

Exception - Any Exception that caused to shutdown process to fail.

getName

public final String getName()

Returns the name of this Agent.

Returns:

name of this Agent

getAgentInfo

public AgentInfo getAgentInfo()

Returns AgentIfno instance associated with this Agent.

Returns:

AgentIfno instance associated with this Agent

getScheduler

public Scheduler getScheduler()

Returns Scheduler used by this Agent. Subsystem developers are encouraged to use this scheduler to running all periodic and delayed tasks.

Returns:

Scheduler provided by this Agent

getCommandCount

public int getCommandCount(Command.CommandType... types)

Returns the number of currently running commands of given types. Note that unless this method is called while holding commandExecutorLock monitor, the returned value is not guaranteed to be current when the method returns.

Parameters:

types - Types of commands to include in the count. In no types are given, all commands are included.

Returns:

number of currently running commands of given types

getStatusBroadcastPeriod

public int getStatusBroadcastPeriod()

Returns heartbeat broadcasting period for this Agent.

Returns:

period (in seconds) for status broadcasting.

isInEngineeringMode

@Command(description="is the system in engineering mode ?",
         type=QUERY,
         category=SYSTEM)
public boolean isInEngineeringMode()

Command to tell if the subsystem is in Engineering mode.

Returns:

true if this Agent is in ENGINEERING_OK or ENGINEERING_FAULT mode.

getCCSVersions

@Command(description="Get the CCS Versions for the current CCS Environment",
         type=QUERY,
         category=SYSTEM)
public CCSVersions getCCSVersions()

Command to get the CCSVersions object for the current CCS Environment.

Returns:

The CCSVersions object for the current CCS Environment

getDistributionInfo

@Command(description="Get the Agent\'s DistributionInfo object.",
         type=QUERY,
         category=SYSTEM)
public DistributionInfo getDistributionInfo()

Command to get the DistributionInfo object for this Agent. The DistributionInfo object contains version information about the distribution from which this Agent was launched.

Returns:

The DistributionInfo for this Agent.

getDictionaries

@Command(description="get the command dictionary for the subsystem",
         type=QUERY,
         category=SYSTEM)
public HashMap<String,Dictionary> getDictionaries()

Returns the command dictionary used by this Agent.

Returns:

getCommandTargets

@Command(description="Get the list of command targets",
         type=QUERY,
         category=SYSTEM)
public List<String> getCommandTargets()

Returns this Agent list of command targets.

Returns:

The list of Command targets.

getCommandSet

protected CommandSet getCommandSet(String name)

addCommandSet

protected void addCommandSet(String name,
                             CommandSet commandSet)

Adds a CommandSet to extend the set of commands recognized by this Agent.

Parameters:

name - name of the command set

commandSet - command set

addCommandsFromObject

public void addCommandsFromObject(Object obj,
                                  String path)

Add the commands defined in an Object to this Agent's CommandSet.

Parameters:

obj - The Object from which to extract the commands.

path - The path at which the resulting CommandSet will be added.

setAgentProperty

public void setAgentProperty(String property,
                             String value)

Set an Agent property. This method can be invoked only up to the point the Agent is about to connect to the buses. Once the messaging factory is create, the AgentInfo object of this Agent must be immutable.

Parameters:

property - The name of the property to set.

value - The value of the property.

getMessagingAccess

public AgentMessagingLayer getMessagingAccess()

Returns AgentMessagingLayer used by this Agent. The returned instance is used by the Agent internally, and can also be used by the client code to publish messages on the buses.

Returns:

AgentMessagingLayer used by this Agent

getEnvironmentMessagingAccess

@Deprecated
public static AgentMessagingLayer getEnvironmentMessagingAccess()

Deprecated.

Returns AgentMessagingLayer associated with this JVM. Normally, there is only one instance of AgentMessagingLayer per JVM, providing busses access to the Agent and all its clients. In the test environment, however, multiple agents can run on the same JVM.

Returns:

AgentMessagingLayer associated with this JVM

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.

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.

getState

public StateBundle getState()

Returns a copy of a state bundle of this Agent.

Returns:

state for the specified class.

updateAgentState

public void updateAgentState(String extraInfo,
                             Enum... stateChanges)

Updates the state of this Agent and publishes StateChangeNotification message. 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.

Parameters:

extraInfo - Information to be included with the state change notification.

stateChanges - The list of the states that have changed.

Throws:

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

updateInternalState

protected final void updateInternalState(String extraInfo,
                                         AgentState... stateChanges)

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

Parameters:

extraInfo - Information to be included with the state change notification.

stateChanges - The list of the states that have changed.

Throws:

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

publishStateChange

protected void publishStateChange(String extraInfo,
                                  StateBundle before,
                                  StateBundle after)

Publishes state transition. Both parameters are assumed to be owned by this method, no copies will be made.

Parameters:

extraInfo - Information to be included with the state change notification.

before - states before the transition

after - states after the transition

publishSubsystemDataOnStatusBus

public final void publishSubsystemDataOnStatusBus(KeyValueData keyValueData)

Publishes the provided KeyValueData on the Status bus. Internally the KeyValueData is wrapped into a StatusSubsystemData before publication.

Parameters:

keyValueData - The KeyValueData to be published.

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.

broadcastStatus

protected final void broadcastStatus()

Broadcasts the current heartbeat status.

updateHeartBeat

protected void updateHeartBeat(StatusHeartBeat heartBeat)

Subclasses can override this method to add customized information to the heartbeat.

Parameters:

heartBeat - Heartbeat instance to be modified before publication.

executeCommandRequest

public void executeCommandRequest(CommandRequest request)

Description copied from interface: CommandExecutor

Executes the received command

Specified by:

executeCommandRequest in interface CommandExecutor

Parameters:

request - the command to be executed by the CommandExecutor

sendNack

public boolean sendNack(Serializable reason)

Sends a NACK to the command originator. This method can be called from inside methods annotated as commands with autoAck=false. It should be called on the same thread the command method was invoked on. If this method is called under any other circumstances, it has no effect and returns false. The value returned by the command method after sending NACK is ignored.

Parameters:

reason - Reason for rejecting the command.

Returns:

true if the NACK has been sent as a result of this call.

sendAck

public boolean sendAck(Duration timeout)

Sends an ACK to the command originator. This method can be called from inside methods annotated as commands with autoAck=false. It should be called on the same thread the command method was invoked on. If this method is called under any other circumstances, it has no effect and returns false.

Parameters:

timeout - Timeout for the command. Specifying non-positive or null timeout indicates the default should be used.

Returns:

true if the ACK has been sent as a result of this call.

getCurrentAction

public Agent.RunningCommand getCurrentAction()

Get the current RunningCommand action.

Returns:

The current RunningCommand for the action.