ariba.util.core
Interface GlobalLockingService

public interface GlobalLockingService

provide services for acquiring global locks and creating lock groups. Global Locks provide cluster-wide synchronization. . A lock is identified by its name. The name must be unique. . A lock is represented by a lock object. There can be only one valid (i.e. locked and unexpired) lock object for the lock throughout the cluster. . You can obtain a lock only if it is currently unlocked. . A lock is created if it does not exist. It is created in the locked state. . Each lock has a specific lifetime. If that lifetime is exceeded, the lock expires, and becomes unlocked. . A lock is acquired with the default lifetime (currently 2 minutes). The lifetime must be extended if the lock is to be held longer than that. . If a lock expires, a cleanup notification will be sent when the lock is next acquired. The notification is posted on a local topic to the default Notification Center. . All lock operations other than acquiring the lock are performed on the lock object. . All operations on an invalid (expired or released) lock object throw an exception. . No synchronization is done on any of these methods. If the user wishes to share a lock object between threads on a node, the user is responsible for proper synchronization. . An acquired lock can be added to a Lock Group. Once added, the lock can be later acquired through a request to the Lock Group. . When a node goes down, all locks acquired by that node become expired. However, the lock may not become available until the node restarts. This means that a lock that becomes available due to a node crashing will always have the cleanup notification sent when the lock is next acquired. . On Cluster Restart, Global Locking is initialized (i.e. there are no locks, and there are no lock groups). This is necessary, or else creating new Lock Groups with different numbers of locks becomes unnecessarily complicated.

Field Summary

static java.lang.String

CleanupTopic

Method Summary

GlobalLock	acquireLock(java.lang.String lockName) Acquire requested GlobalLock.
GlobalLock	acquireLock(java.lang.String lockName, long acquireTimeout) Aacquire requested GlobalLock with an acquistion timeout.
GlobalLock	acquireLockFromGroup(java.lang.String groupName) Acquire a lock from the requested lock group.
GlobalLock	acquireLockFromGroup(java.lang.String groupName, long acquireTimeout) Acquire a lock from the requested lock group.
void	createLockGroup(java.lang.String groupName, int numLocks) Create a new lock group, and allow numLocks locks to be assigned to it.
void	createLockPool(java.lang.String groupName, int numLocks) Create a new lockgroup, and a pool of locks for it.
void	deleteLockGroup(java.lang.String groupName) Delete the specified lock group.
boolean	nodeHasLock(java.lang.String lockName, java.lang.String nodeName) Returns true if the specified lock is held by the specified node.

Field Detail

CleanupTopic

static final java.lang.String CleanupTopic

See Also:

Constant Field Values

Method Detail

acquireLock

GlobalLock acquireLock(java.lang.String lockName)

Acquire requested GlobalLock. If the lock does not exist, it is created and obtained. Return immediately if the lock is not available.

Parameters:

lockName - The name of the lock. Must be unique

Returns:

The lock object, or null if the lock is not free

acquireLock

GlobalLock acquireLock(java.lang.String lockName,
                       long acquireTimeout)

Aacquire requested GlobalLock with an acquistion timeout. If the lock does not exist, it is created and obtained. Try to obtain the lock for specified number of milliseconds, then return a null if the lock is not available.

Parameters:

lockName - The name of the lock. Must be unique

acquireTimeout - The number of milliseconds to try for

Returns:

The lock object, or null if the lock is not free

acquireLockFromGroup

GlobalLock acquireLockFromGroup(java.lang.String groupName)
                                throws GlobalLockingException

Acquire a lock from the requested lock group. The lock group must exist, and there must be locks assigned to it. Returns immediatley if no lock is available

Parameters:

groupName - The lock group

Returns:

The lock object if one is available, null otherwise

Throws:

GlobalLockingException - thrown if the lock group does not exist, or if there are no locks assigned to the group.

acquireLockFromGroup

GlobalLock acquireLockFromGroup(java.lang.String groupName,
                                long acquireTimeout)
                                throws GlobalLockingException

Acquire a lock from the requested lock group. The lock group must exist, and there must be locks assigned to it. Try to obtain the lock for acquireTimeOut milliseconds before returning.

Parameters:

groupName - The lock group

acquireTimeout - The number of milliseconds to try to obtain the lock

Returns:

The lock object if one is available, null otherwise

Throws:

GlobalLockingException - thrown if the lock group does not exist, or if there are no locks assigned to the group.

createLockGroup

void createLockGroup(java.lang.String groupName,
                     int numLocks)
                     throws GlobalLockingException

Create a new lock group, and allow numLocks locks to be assigned to it. The name must be unique

Parameters:

groupName - The name of the group

numLocks - How many locks can be in this group

Throws:

GlobalLockingException - if the group already exists

createLockPool

void createLockPool(java.lang.String groupName,
                    int numLocks)
                    throws GlobalLockingException

Create a new lockgroup, and a pool of locks for it. The locks are given the name Lock, and are added to the group. Each lock is then released. When this call successfully completes, you may immediately acquire locks by calling acquireLockFromGroup.

Parameters:

groupName - The name of the group to create

numLocks - How many locks to create

Throws:

GlobalLockingException - if the group already exists, or if any of the locks associated with the group already exits and are assigned to the group.

deleteLockGroup

void deleteLockGroup(java.lang.String groupName)
                     throws GlobalLockingException

Delete the specified lock group. The lock group can be deleted only if all the locks in the group are free. If any of the locks are not free, the lockgroup is not deleted.

Parameters:

groupName - The name of the group to delete

Throws:

GlobalLockingException - if the group does not exist, or if any of the locks within the group are locked or expired.

nodeHasLock

boolean nodeHasLock(java.lang.String lockName,
                    java.lang.String nodeName)

Returns true if the specified lock is held by the specified node.

Parameters:

lockName - The name of the lock

nodeName - The name of the node