org.lsst.ccs

Class Agent

java.lang.Object

org.lsst.ccs.Agent

All Implemented Interfaces:

CommandExecutor, ServiceLifecycle

Direct Known Subclasses:

Subsystem

public class Agent
extends Object
implements CommandExecutor, ServiceLifecycle

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.

IMPLEMENTATION NOTE: Agent must not implement HasLifecycle see https://jira.slac.stanford.edu/browse/LSSTCCS-1487

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
static String	AGENT_HEARTBEAT_TASK
static String	AGENT_RUNTIMEINFO_TASK
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 AtomicBoolean	jvmShutdown Flag indicating that shutdownAgent() is being executed in a JVM shutdown hook.
protected LogBusHandler	logBusHandler Logging bus handler
protected AgentStateService	stateService
protected boolean	treeComponentInitialized

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	broadcastStatus() Broadcasts the current heartbeat status.
void	checkAllHardwareStopped() Called to check if all hardware has been correctly started.
protected CommandHelper	createHelper() This method can be overridden by subclasses of Agent to create a subclass of CommandHelper to be returned by helper()
void	executeCommandRequest(CommandRequest request) Executes the received command
AgentInfo	getAgentInfo() Returns AgentIfno instance associated with this Agent.
PersistencyService	getAgentPersistenceService() Get this agent's local persistence service.
<T extends AgentService> T	getAgentService(Class<T> agentClass) Generic method to access agent services.
List<AgentService>	getAgentServices() Get the list of available services for 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.
ComponentConfigurationEnvironment	getComponentConfigurationEnvironment(Object obj) Get the ComponentConfigurationEnvironment object for a given Object.
ComponentConfigurationEnvironment	getComponentConfigurationEnvironmentByName(String name) Get the ComponentConfigurationEnvironment object for a given node name.
ComponentLookup	getComponentLookup() Provides access to the inner modular structure of this Subsystem.
Agent.RunningCommand	getCurrentAction() Get the current RunningCommand action.
String	getDescription() Gets the name of the description this subsystem was built from.
DistributionInfo	getDistributionInfo() Command to get the DistributionInfo object for this Agent.
static AgentLockService	getEnvironmentLockService()
static AgentMessagingLayer	getEnvironmentMessagingAccess() Returns AgentMessagingLayer associated with this JVM.
Logger	getLogger() Returns the current logger (use sparingly and prefer your own logger).
AgentMessagingLayer	getMessagingAccess() Returns AgentMessagingLayer used by this Agent.
String	getName() Returns the name of this Agent.
Scheduler	getScheduler() Returns Scheduler used by this Agent.
int	getStatusBroadcastPeriod() * Returns heartbeat broadcasting period for this Agent.
CommandHelper	helper() A convenience method for creating a new CommandHelper
protected void	internalCheckHardware() Called before activating anything and again once problems are supposed to have been addressed.
boolean	isConnectedToTheBuses()
boolean	isInEngineeringMode() Command to tell if the subsystem is in Engineering mode.
protected void	populateComponentLookup(ComponentLookup lookup) Sets the component lookup for this Agent.
void	preBuild()
String	printComponentNodeTree() Get a representation of the component tree.
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	sendStatusMessage(StatusMessage msg) Temporary method for sending messages on the status bus.
void	setAgentName(String alias)
Object	shutdownAgent() Clean shutdown of subsystem: call stop for hardware stopping before invoking this method.
void	startAgent() Starts this Agent
String	vetoTransitionToNormalMode() Method to be overwritten by Agents that wish to veto the transition to NORMAL mode.

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, preInit, preShutdown, preStart

Field Detail

jvmShutdown

protected final AtomicBoolean jvmShutdown

Flag indicating that shutdownAgent() is being executed in a JVM shutdown hook.

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.

treeComponentInitialized

protected volatile boolean treeComponentInitialized

stateService

@LookupField(strategy=CHILDREN)
protected AgentStateService stateService

AGENT_HEARTBEAT_TASK

public static final String AGENT_HEARTBEAT_TASK

See Also:

Constant Field Values

AGENT_RUNTIMEINFO_TASK

public static final String AGENT_RUNTIMEINFO_TASK

See Also:

Constant Field Values

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

preBuild

public void preBuild()

Specified by:

preBuild in interface ServiceLifecycle

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

getAgentServices

public final List<AgentService> getAgentServices()

Get the list of available services for this Agent.

Returns:

a List of AgentServices

getAgentService

public final <T extends AgentService> T getAgentService(Class<T> agentClass)

Generic method to access agent services.

Type Parameters:

T - The class of the service to fetch.

Parameters:

agentClass -

Returns:

The services of the requested type.

getComponentLookup

public final ComponentLookup getComponentLookup()

Provides access to the inner modular structure of this Subsystem.

Returns:

a ComponentLookup object.

createHelper

protected CommandHelper createHelper()

This method can be overridden by subclasses of Agent to create a subclass of CommandHelper to be returned by helper()

Returns:

The newly created CommandHelper

helper

public CommandHelper helper()

A convenience method for creating a new CommandHelper

Returns:

The newly created CommandHelper

See Also:

createHelper()

setAgentName

public final void setAgentName(String alias)

startAgent

public void startAgent()

Starts this Agent

shutdownAgent

@Command(name="shutdown",
         description="shutdown",
         type=ACTION,
         category=CORE)
public Object shutdownAgent()
                                                                                                                              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

getLogger

public Logger getLogger()

Returns the current logger (use sparingly and prefer your own logger).

Returns:

logger associated with this subsystem

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=CORE)
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.

printComponentNodeTree

@Command(description="Print component lookup",
         type=QUERY,
         category=SYSTEM)
public String printComponentNodeTree()

Get a representation of the component tree.

Returns:

a String representing the component tree

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

getEnvironmentLockService

public static AgentLockService getEnvironmentLockService()

sendStatusMessage

public void sendStatusMessage(StatusMessage msg)

Temporary method for sending messages on the status bus. This method is to guarantee that the StateBundle information is consistent for all messages sent on the buses. See: https://jira.slac.stanford.edu/browse/LSSTCCS-1577

Parameters:

msg - The StatusMessage to send on the buses.

isConnectedToTheBuses

public boolean isConnectedToTheBuses()

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.

broadcastStatus

protected final void broadcastStatus()

Broadcasts the current heartbeat status.

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.

getComponentConfigurationEnvironment

public ComponentConfigurationEnvironment getComponentConfigurationEnvironment(Object obj)

Get the ComponentConfigurationEnvironment object for a given Object.

Parameters:

obj - the object for which to get the component configuration service

Returns:

a component configuration service for the given object

getComponentConfigurationEnvironmentByName

public ComponentConfigurationEnvironment getComponentConfigurationEnvironmentByName(String name)

Get the ComponentConfigurationEnvironment object for a given node name.

Parameters:

name - the name of the object for which to get the component configuration service.

Returns:

a component configuration service for the given object.

getAgentPersistenceService

public PersistencyService getAgentPersistenceService()

Get this agent's local persistence service.

Returns:

the local persistence service for this agent.

getDescription

public String getDescription()

Gets the name of the description this subsystem was built from. The description name is set after the initialization step.

Returns:

the description name

internalCheckHardware

protected void internalCheckHardware()

Called before activating anything and again once problems are supposed to have been addressed. It invokes a checkHardware on all HardwareController (except when return diag modifies the path of invocation)

checkAllHardwareStopped

public void checkAllHardwareStopped()
                             throws HardwareException

Called to check if all hardware has been correctly started. It checks if all HardwareControllers have been stopped

Throws:

HardwareException - a compound exception that list the exceptions fired by hardwares that are not stopped.

vetoTransitionToNormalMode

public String vetoTransitionToNormalMode()

Method to be overwritten by Agents that wish to veto the transition to NORMAL mode.

Returns:

null if it's ok to transition to NORMAL mode. Otherwise return the String for the reason the transition has been vetoed. The String will be returned as part of the Nack.