org.lsst.ccs.services

Class AgentLockService

java.lang.Object

org.lsst.ccs.services.AgentLockService

All Implemented Interfaces:

AgentPresenceListener, LockLevelService, ServiceLifecycle, AgentService

public class AgentLockService
extends Object
implements LockLevelService, AgentPresenceListener, ServiceLifecycle, AgentService

Client side locking service, for a given agent. It is attached to an instance of Agent, which is any agent with type >= CONSOLE. It provides an API both for consoles that need to lock/unlock a WORKER subsystem, and for WORKER subsystem that need to check the validity of a lock attached with a command request. It encapsulates the communication protocol with the centralized LockManager subsystem.

Author:

LSST CCS Team

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AgentLockService.AgentLevelListener Interface for being notified of subsystem level change events.
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	addAgentLevelListener(AgentLockService.AgentLevelListener l)
void	addAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener slul)
void	connecting(AgentInfo ai) Indicates that the agent represented by agent is present on the buses.
String	getAgentServiceName() Get the name of this service.
List<String>	getAllWorkerAgents()
Map<String,AgentLock>	getHeldLocks() Get information of the locks currently held by this agent.
int	getLevelForAgent(String agentName) Get this agent's authorized level at which it can operate the given agentName.
List<String>	getLockableAgents()
List<String>	getLockedAgents()
AgentLock	getLockForAgent(String agentName) Returns a lock held by the associated agent on the given agentName, or null if the associated agent does not hold a lock on the given agent
Map<String,AgentLock>	getLocks() Get information on all the current existing locks in a cluster of subsystems.
void	lockAgent(String agentName) Request for this agent to obtain a lock on the given subsystem.
void	preInit()
void	removeAgentLevelListener(AgentLockService.AgentLevelListener l)
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.messaging.AgentPresenceListener

connecting, disconnecting

Methods inherited from interface org.lsst.ccs.ServiceLifecycle

preBuild, preShutdown, preStart

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

startForAgent

Constructor Detail

AgentLockService

public AgentLockService()

Method Detail

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

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)

Get this agent's authorized level at which it can operate the given agentName. It returns 0 if this agent does not hold a lock on agentName.

Specified by:

getLevelForAgent in interface LockLevelService

Parameters:

agentName - the agent to get the level for.

Returns:

a level. If there is no level defined for this agent, return 0.

getLockForAgent

public AgentLock getLockForAgent(String agentName)

Returns a lock held by the associated agent on the given agentName, or null if the associated agent does not hold a lock on the given agent

Specified by:

getLockForAgent in interface LockLevelService

Parameters:

agentName -

Returns:

an AgentLock object or

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.

Parameters:

agentName -

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 IOException

Request for this agent to release a lock on the given subsystem. If successful, this agent will own a lock on the requested subsystem. Registered AgentLockUpdateListener and AgentLevelListener will be notified. The list of owned valid locks will be updated.

Parameters:

agentName -

Throws:

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

getLocks

public Map<String,AgentLock> getLocks()

Get information on all the current existing locks in a cluster of subsystems. This information will be updated by listening on Lock Messages on the buses.

Returns:

a map of subsystem names to their current lock.

getHeldLocks

public Map<String,AgentLock> getHeldLocks()

Get information of the locks currently held by this agent. This information will be updated by listening on Lock Messages on the buses.

Returns:

a map of subsystem names to their lock.

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.

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

addAgentLevelListener

public void addAgentLevelListener(AgentLockService.AgentLevelListener l)

Parameters:

l -

removeAgentLevelListener

public void removeAgentLevelListener(AgentLockService.AgentLevelListener l)

addAgentLockUpdateListener

public void addAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener slul)

Parameters:

slul -

removeAgentLockUpdateListener

public void removeAgentLockUpdateListener(AgentLockService.AgentLockUpdateListener l)

connecting

public void connecting(AgentInfo ai)

Description copied from interface: AgentPresenceListener

Indicates that the agent represented by agent is present on the buses. The implementation should return immediately : any blocking operations should be scheduled on a separate thread.

Specified by:

connecting in interface AgentPresenceListener

getLockableAgents

public List<String> getLockableAgents()

getLockedAgents

public List<String> getLockedAgents()

getAllWorkerAgents

public List<String> getAllWorkerAgents()