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.
• 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.
class	Agent.ShutdownResult

Field Summary

Fields

Modifier and Type	Field and Description
static String	AGENT_DESCRIPTION
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 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.
int	getCommandCount(Command.CommandType... types) Returns the number of currently running commands of given types.
ComponentConfigurationEnvironment	getComponentConfigurationEnvironment(Object obj) Deprecated. Use ConfigurationService instead.
ComponentConfigurationEnvironment	getComponentConfigurationEnvironmentByName(String name) Deprecated. Use ConfigurationService instead.
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.
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() Get the underlying AgentMessagingLayer instance.
String	getName() Returns the name of this Agent.
Scheduler	getScheduler() Returns Scheduler used by this Agent.
CommandHelper	helper() A convenience method for creating a new CommandHelper
void	initAgent()
void	initLogBusHandler() connects a LogBusHandler to the Log bus.
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	preInit()
void	preStart() Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#start() has been called.
String	printComponentNodeTree() Get a representation of the component tree.
void	publishMonitoringDataOnStatusBus(KeyValueData keyValueData) This method should only be used by Monitor.java to publish monitoring data
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) 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.
protected Object	shutdownAgent(boolean goOffline)
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

afterBuild, afterInit, afterStart, preBuild, preShutdown

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_RUNTIMEINFO_TASK

public static final String AGENT_RUNTIMEINFO_TASK

See Also:

Constant Field Values

AGENT_DESCRIPTION

public static final String AGENT_DESCRIPTION

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

preInit

public void preInit()

Specified by:

preInit 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

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

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)

initAgent

public final void initAgent()

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

shutdownAgent

protected Object shutdownAgent(boolean goOffline)
                        throws Exception

Throws:

Exception

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

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.

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()

Get the underlying AgentMessagingLayer instance. Alternatively use MessagingService::getMessagingAccess();

Returns:

the underlying AgentMessagingLayer.

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)

Method for sending messages on the status bus.

Parameters:

msg - The StatusMessage to send on the buses.

initLogBusHandler

public void initLogBusHandler()

connects a LogBusHandler to the Log bus. Should be called only when messaging is initialized properly.

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.

publishMonitoringDataOnStatusBus

public final void publishMonitoringDataOnStatusBus(KeyValueData keyValueData)

This method should only be used by Monitor.java to publish monitoring data

Parameters:

keyValueData -

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

@Deprecated
public ComponentConfigurationEnvironment getComponentConfigurationEnvironment(Object obj)

Deprecated. Use ConfigurationService instead.

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

@Deprecated
public ComponentConfigurationEnvironment getComponentConfigurationEnvironmentByName(String name)

Deprecated. Use ConfigurationService instead.

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

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.