Package org.lsst.ccs.services

Class AgentLockService

java.lang.Object
org.lsst.ccs.services.AgentLockService
All Implemented Interfaces:
LockLevelService, ServiceLifecycle, AgentService
public class AgentLockService extends Object implements LockLevelService, ServiceLifecycle, AgentService

  • Field Details

  • Constructor Details

    • AgentLockService

      public AgentLockService()

  • Method Details

    • getAgentStateService

      public AgentStateService getAgentStateService()

    • getAgentLoginService

      public AgentLoginService getAgentLoginService()

    • getAgentServiceName

      public String getAgentServiceName()
      Description copied from interface: AgentService
      Get the name of this service. This name will be used to add the given service to the lookup tree.
      Specified by:
      getAgentServiceName in interface AgentService
      Returns:
      the AgentService name.

    • preInit

      public void preInit()
      Specified by:
      preInit in interface ServiceLifecycle

    • 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

    • setLevelForAgent

      public void setLevelForAgent(String agentName, int level) throws UnauthorizedLevelException, UnauthorizedLockException
      Set this agent's operational level for the given subsystem. If this agent does not hold a lock on the subsystem, this method will first attempt to acquire a lock on the subsystem. If successful, registered AgentLevelListener will be notified with the new level value.
      Parameters:
      agentName - Target subsystem name.
      level - Desired level.
      Throws:
      UnauthorizedLevelException - If the lock on the target subsystem has been successfully acquired, but the desired level cannot be set because the current user is not authorized to operate at that level.
      UnauthorizedLockException - If the target subsystem cannot be locked.
      RuntimeException - If there was a communication problem on the buses.

    • getLevelForAgent

      public int getLevelForAgent(String agentName)
      Returns this agent's authorized level at which it can operate the specified subsystem. Returns 0 if there is no lock owned by the current user and attached to this agent.
      Specified by:
      getLevelForAgent in interface LockLevelService
      Parameters:
      agentName - Target subsystem name.
      Returns:
      Current level, or 0 if there is no attached lock.

    • getLockForAgent

      public AgentLock getLockForAgent(String agentName)
      Returns a lock for the specified subsystem if there is one attached to this agent, null otherwise. In order to be returned by this method, the lock must be owned by the current user and attached to this agent.
      Specified by:
      getLockForAgent in interface LockLevelService
      Parameters:
      agentName - Target subsystem name.
      Returns:
      Lock for the target subsystem if there is one attached.

    • getExistingLockForAgent

      public AgentLock getExistingLockForAgent(String agentName)
      Returns a lock for the specified subsystem if there is one, null otherwise. The lock might be owned by any user and attached to any agent.
      Parameters:
      agentName - Target subsystem name.
      Returns:
      Lock for the target subsystem if it exists, null otherwise.

    • lockAgent

      public void lockAgent(String agentName) throws UnauthorizedLockException
      Request for this agent to obtain a lock on the given subsystem. If successful, this agent will own a lock on the requested subsystem. registered AgentLockUpdateListener will be notified. The list of owned valid locks will be updated. This command will return only when the lock has been acknowledged trough network exchanges.
      Parameters:
      agentName - Target subsystem name.
      Throws:
      UnauthorizedLockException - If the target subsystem cannot be locked.
      RuntimeException - If there was a communication problem on the buses.

    • unlockAgent

      public void unlockAgent(String agentName) throws UnauthorizedLockException
      Request to release a lock on the given subsystem. If successful, current user will lose its lock on the requested subsystem. All agents that have attached the lock will lose their version of it and be notified. Registered AgentLockUpdateListener will be notified. The list of owned valid locks will be updated. Non-blocking. Calling this method for an agent that is already unlocked has no effect.
      Parameters:
      agentName - Target subsystem name.
      Throws:
      UnauthorizedLockException - If the target is locked, and the lock is not owned by the current user.
      RuntimeException - If there was a communication problem on the buses.

    • attachLock

      public void attachLock(String agentName) throws UnauthorizedLockException
      Request for this agent to attach a lock on the given subsystem that is already owned by the user. The list of owned valid locks will be updated. Registered AgentLockUpdateListener will be notified. This command will return only when the lock has been acknowledged trough network exchanges.
      Parameters:
      agentName - Target subsystem name.
      Throws:
      UnauthorizedLockException - If the user does not own a lock on the specified subsystem.
      RuntimeException - If there was a communication problem on the buses.

    • detachLock

      public void detachLock(String agentName) throws UnauthorizedLockException
      Request for this agent to detach a lock on the given subsystem. If successful, this agent will lose its version of the lock on the requested subsystem, but the lock will still exist and be associated to the user. Registered AgentLockUpdateListener will be notified. The list of owned valid locks will be updated. Non-blocking.
      Parameters:
      agentName - Target subsystem name.
      Throws:
      UnauthorizedLockException - If the user does not have a lock on the specified subsystem.
      RuntimeException - If there was a communication problem on the buses.

    • getLocks

      public Map<String,AgentLock> getLocks()
      Returns a map of all existing locks, regardless of who owns them and what agents they are attached to. The returned map will be updated as locks are modified, created, or destroyed.
      Returns:
      a map of subsystem names to their current lock.

    • getHeldLocks

      public Map<String,AgentLock> getHeldLocks()
      Returns a map of attached locks. To be included, a lock must be owned by the current user and attached to this agent. The returned map is a snapshot produced at the time this method is called, and it will not be updated.
      Returns:
      Map of target subsystem names to their locks.

    • validateLock

      public String validateLock(DictionaryCommand command, CommandRequest request)
      Validates a lock object. This can be used by a worker subsystem to validate a lock attached to a command request.
      Parameters:
      command - Command.
      request - Command request.
      Returns:
      Error description if the lock is invalid, null otherwise.

    • getUserId

      public String getUserId()
      Returns the current user.
      Specified by:
      getUserId in interface LockLevelService
      Returns:
      Current user ID.

    • addAgentLockUpdateListener

      public void addAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener slul)

    • removeAgentLockUpdateListener

      public void removeAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener l)

    • getLockableAgents

      public List<String> getLockableAgents()
      Returns a list of subsystems that can be locked by are not currently locked by anyone.
      Returns:
      List of lockable subsystems.

    • getAttachableAgents

      public List<String> getAttachableAgents()
      Returns a list of subsystems locked by the current user but not attached by this subsystem.
      Returns:
      List of attachable subsystems.

    • getDetachableAgents

      public List<String> getDetachableAgents()
      Returns a list of subsystems locked by the current user and attached by this subsystem.
      Returns:
      List of attached subsystems.

    • getLockedAgents

      public List<String> getLockedAgents()
      Returns a list of subsystems locked by the current user.
      Returns:
      List of subsystems locked by the current user.

    • getAllLockedAgents

      public List<String> getAllLockedAgents()
      Returns a list of currently locked subsystems, regardless of whom they are locked by.
      Returns:
      List of subsystems locked by any user.

    • getLocallyLockedAgents

      public List<String> getLocallyLockedAgents()
      Returns a list of subsystems locked by the current user and attached by this subsystem. Convenience method, same as getDetachableAgents().
      Returns:
      List of attached subsystems.

    • getAllWorkerAgents

      public List<String> getAllWorkerAgents()

    • destroyLock

      public void destroyLock(String agentName, String userId)
      Destroys a lock. Use in emergency.
      Parameters:
      agentName - Target subsystem name.
      userId - User on whose authority the lock should be destroyed.

    • getMaxLevel

      public int getMaxLevel(String user, String agentName)
      Returns maximum level at which the specified user is allowed to lock the specified agent.
      Parameters:
      user - User ID.
      agentName - Target agent.
      Returns:
      Maximum allowed level.

    • getMaxLevelsUser

      public static Map<String,Integer> getMaxLevelsUser(String user, Map<String,Map<String,String>> config)
      For the given user, returns a map of subsystem name or name wildcard to maximum allowed level. Groups are expanded, level names decoded.
      Parameters:
      user - User ID.
      config - Lock manager configuration parameter that defines max levels for all users and agents.
      Returns:
      Map of subsystem name or name wildcard to maximum level. May be empty but never null.

    • getMaxLevelsSubsystem

      public static Map<String,Integer> getMaxLevelsSubsystem(String agentName, Map<String,Map<String,String>> config)
      For the given agent, returns a map of users to maximum allowed levels.
      Parameters:
      agentName - Agent that executes commands.
      config - Lock manager configuration parameter that defines max levels for all users and agents.
      Returns:
      Map of user ID to max level. May be empty but never null.