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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AgentLockService.AgentLockUpdateListener Interface for being notified of lock update events.

Constructor Summary

Constructors

Constructor and Description
AgentLockService()

Method Summary

Modifier and Type	Method and Description
void	addAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener slul)
void	attachLock(String agentName) Request for this agent to attach a lock on the given subsystem that is already owned by the user.
void	destroyLock(String agentName, String userId) Destroys a lock.
void	detachLock(String agentName) Request for this agent to detach a lock on the given subsystem.
AgentLoginService	getAgentLoginService()
String	getAgentServiceName() Get the name of this service.
AgentStateService	getAgentStateService()
List<String>	getAllWorkerAgents()
List<String>	getAttachableAgents()
List<String>	getDetachableAgents()
AgentLock	getExistingLockForAgent(String agentName) Returns a lock for the specified subsystem if there is one, null otherwise.
Map<String,AgentLock>	getHeldLocks() Returns a map of attached locks.
int	getLevelForAgent(String agentName) Returns this agent's authorized level at which it can operate the specified subsystem.
List<String>	getLocallyLockedAgents()
List<String>	getLockableAgents()
List<String>	getLockedAgents()
AgentLock	getLockForAgent(String agentName) Returns a lock for the specified subsystem if there is one attached to this agent, null otherwise.
Map<String,AgentLock>	getLocks() Returns a map of all existing locks, regardless of who owns them and what agents they are attached to.
String	getUserId() Returns the current user.
void	lockAgent(String agentName) Request for this agent to obtain a lock on the given subsystem.
void	preInit()
void	preStart() Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#start() has been called.
void	removeAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener l)
void	setLevelForAgent(String agentName, int level) Set this agent's operational level for the given subsystem.
void	unlockAgent(String agentName) Request for this agent to release a lock on the given subsystem.
boolean	validateLock(AgentLock lock) Validate a lock object.

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

Methods inherited from interface org.lsst.ccs.services.AgentService

startForAgent

Constructor Detail

AgentLockService

public AgentLockService()

Method Detail

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,
                             IOException

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 - the subsystem for which to change the level

level - the level to set

Throws:

UnauthorizedLevelException - if the requested level cannot be set. This happens if this agent owns a lock on the given subsystem and that lock defines a maximum level that is lower than the requested level, or if this agent does not hold a lock on the given subsystem and this agent's default subsystem level is lower than the requested level.

UnauthorizedLockException - if the user is not allowed to acquire a lock on the specified Agent

IOException - 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,
                      IOException

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 user is not allowed to acquire a lock on the specified Agent

IOException - if there was a communication problem on the buses.

unlockAgent

public void unlockAgent(String agentName)
                 throws UnauthorizedLockException,
                        IOException

Request for this agent to release a lock on the given subsystem. If successful, this agent will lose its lock on the requested subsystem. All agents having attached the lock will lose their version of the lock and be notified. 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 did not have a lock on the specified Agent

IOException - if there was a communication problem on the buses.

attachLock

public void attachLock(String agentName)
                throws UnauthorizedLockException,
                       IOException

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 tbrough network exchanges.

Parameters:

agentName - Target subsystem name.

Throws:

UnauthorizedLockException - if the user is not allowed to acquire a lock on the specified Agent

IOException - if there was a communication problem on the buses.

detachLock

public void detachLock(String agentName)
                throws UnauthorizedLockException,
                       IOException

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 did not have a lock on the specified Agent

IOException - 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 boolean validateLock(AgentLock lock)

Validate a lock object. This can be used for a worker subsystem to validate a lock attached to a command request. It will check the worker is the target of this lock, and the lock is known.

Parameters:

lock - the lock object to validate

Returns:

true if the lock is valid, i.e. it is the lock that is currently locking this agent

getUserId

public String getUserId()

Returns the current user.

Returns:

Current user ID.

addAgentLockUpdateListener

public void addAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener slul)

Parameters:

slul -

removeAgentLockUpdateListener

public void removeAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener l)

getLockableAgents

public List<String> getLockableAgents()

getAttachableAgents

public List<String> getAttachableAgents()

getDetachableAgents

public List<String> getDetachableAgents()

getLockedAgents

public List<String> getLockedAgents()

getLocallyLockedAgents

public List<String> getLocallyLockedAgents()

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.