Package org.lsst.ccs

Class Agent

java.lang.Object
org.lsst.ccs.Agent
All Implemented Interfaces:
CommandExecutor, ServiceLifecycle
Direct Known Subclasses:
DumpCommands, 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

  • Field Details

    • 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:

    • AGENT_DESCRIPTION

      public static final String AGENT_DESCRIPTION
      See Also:

  • Constructor Details

    • 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 Details

    • 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:

    • setAgentName

      public final void setAgentName(String alias)

    • initAgent

      public final void initAgent()

    • startAgent

      public void startAgent()
      Starts this Agent

    • shutdownAgent

      public Object shutdownAgent() throws Exception
      Throws:
      Exception

    • shutdownAgent

      @Command(name="shutdown", description="shutdown", type=ACTION, category=CORE) public Object shutdownAgent(@Argument(description="Seconds before the subsystem is expected to restart",defaultValue="0") int nSeconds) throws Exception
      Clean shutdown of subsystem: call stop for hardware stopping before invoking this method.
      Parameters:
      nSeconds - Number of seconds before the system is expected to restart.
      Returns:
      Status of the shutdown
      Throws:
      Exception - If anything goes wrong during shutdown

    • shutdownAgent

      protected Object shutdownAgent(boolean goOffline, int nSeconds) 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.

    • 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.

    • getCommandForThisThread

      public Agent.RunningCommand getCommandForThisThread()
      Returns handle of RunningCommand currently being executed by this thread.
      Returns:
      Current command, or null if this thread is not executing a command.

    • getCommandUser

      public String getCommandUser()
      Returns userid of the agent that submitted the command currently being executed by this thread.
      Returns:
      User name, or null if this thread is not executing a command.

    • 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.