org.lsst.ccs

Class Agent

java.lang.Object

org.lsst.ccs.Agent

All Implemented Interfaces:

HasAgentPeriodicTasks, CommandExecutor

Direct Known Subclasses:

Subsystem

public class Agent
extends Object
implements CommandExecutor, HasAgentPeriodicTasks

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 Object	innerStateLock Lock for innerState variable.
protected LogBusHandler	logBusHandler Logging bus handler
protected static Map<Object,Agent>	OBJECT_SUBSYSTEM_MAP

Constructor Summary

Constructors

Modifier	Constructor and Description
	Agent(String name, AgentInfo.AgentType agentType) Constructs an Agent.
protected	Agent(String name, AgentInfo.AgentType agentType, ComponentLookup componentLookup)

Method Summary

Modifier and Type	Method and Description
protected void	addCommandSet(String fullPath, 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	addInternalNodes()
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.
List<AgentPeriodicTask>	getAgentPeriodicTasks() Get the list of the AgentPeriodicTasks to be executed by the framework.
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.
ComponentLookup	getComponentLookup() Provides access to the inner modular structure of this Subsystem.
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() Returns AgentMessagingLayer associated with this JVM.
AgentMessagingLayer	getMessagingAccess() Returns AgentMessagingLayer used by this Agent.
String	getName() Returns the name of this Agent.
long	getPeriodicTaskPeriod(String taskName) Get the period of a PeriodicTaks.
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	populateComponentLookup(ComponentLookup lookup) Sets the component lookup for this Agent.
void	postStart() Called by the framework after subsystem has been started.
protected void	publishStateChange(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.
void	setPeriodicTaskPeriod(String taskName, long period) Change the period of a PeriodicTask.
Object	shutdown() Clean shutdown of subsystem: call stop for hardware stopping before invoking this method.
void	start() Deprecated. use startAgent() instead
void	startAgent() Starts this Agent
void	updateAgentState(Enum... stateChanges)
void	updateAgentState(String extraInfo, Enum... stateChanges) Deprecated. use updateAgentState(Enum... stateChagnes) instead
protected void	updateHeartBeat(StatusHeartBeat heartBeat) Subclasses can override this method to add customized information to the heartbeat.
protected 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

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.

OBJECT_SUBSYSTEM_MAP

protected static final Map<Object,Agent> OBJECT_SUBSYSTEM_MAP

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.

Agent

protected Agent(String name,
                AgentInfo.AgentType agentType,
                ComponentLookup componentLookup)

Method Detail

populateComponentLookup

protected final void populateComponentLookup(ComponentLookup lookup)

Sets the component lookup for this Agent. This method is meant to be invoked from two places: - a constructor - BootUtils after a Subsystem has been built

Parameters:

lookup - the lookup

addInternalNodes

protected void addInternalNodes()

getComponentLookup

public final ComponentLookup getComponentLookup()

Provides access to the inner modular structure of this Subsystem.

Returns:

a ComponentLookup object.

startAgent

public void startAgent()

Starts this Agent

start

@Deprecated
public void start()

Deprecated. use startAgent() instead

Starts this Agent

postStart

public void postStart()
               throws HardwareException

Called by the framework after subsystem has been started. Can be overridden by subclasses to provide subsystem-specific post-initialization actions.

Throws:

HardwareException - because some "homing" operations may be tried by the hardware

setPeriodicTaskPeriod

public void setPeriodicTaskPeriod(String taskName,
                                  long period)

Change the period of a PeriodicTask. This method is to be used by subsystem developers to change the period of a periodic task.

Parameters:

taskName - The name of the task

period - The period in milliseconds

getPeriodicTaskPeriod

public long getPeriodicTaskPeriod(String taskName)

Get the period of a PeriodicTaks.

Parameters:

taskName - The name of the task

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 for running all periodic and delayed short 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 fullPath,
                             CommandSet commandSet)

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

Parameters:

commandSet - command set

fullPath - the full path of the component to add

addCommandsFromObject

public void addCommandsFromObject(Object obj,
                                  String path)

Add the commands defined in an Object to this Agent's CommandSet. This method will end up throwing a RuntimeException if it is invoked after the Agent has been started. This is because the internal method addCommandSet is protected against such an event.

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

public static AgentMessagingLayer getEnvironmentMessagingAccess()

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

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

Deprecated. use updateAgentState(Enum... stateChagnes) instead

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. Since this method produces a status publication it must be invoked after the Agent has joined the buses. For example the first publication of the Agent specific states could be done in the postStart method of HasLifecycle

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.

updateAgentState

public void updateAgentState(Enum... stateChanges)

updateInternalState

protected 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

publishStateChange

protected void publishStateChange(StateBundle before,
                                  StateBundle after)

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

Parameters:

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.

getAgentPeriodicTasks

public List<AgentPeriodicTask> getAgentPeriodicTasks()

Description copied from interface: HasAgentPeriodicTasks

Get the list of the AgentPeriodicTasks to be executed by the framework. This method is invoked when the ComponentLookup is set on the Subsystem, i.e. right after the objects on the ComponentLookup are built. So this list must be built either in the constructor or in the method itself.

Specified by:

getAgentPeriodicTasks in interface HasAgentPeriodicTasks

Returns:

The List of PeriodicTasks.

getCurrentAction

public Agent.RunningCommand getCurrentAction()

Get the current RunningCommand action.

Returns:

The current RunningCommand for the action.