com.h3c.dist.lock

Interface LockService

All Known Subinterfaces:

HAService

public interface LockService

Locking service applications use the Interface to get objects of different types of Locks LockType.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	changeOwner(Lock lock, ApplicationId appId) Change the ownership of a set of read and/or write locks.
Lock	createMultiLock(ApplicationId appId, LockName name, List<LockNameType> locks) Create a lock object that represents a pool of locks requested.
Lock	createReadLock(ApplicationId appId, LockName name) Get read lock object.
Lock	createWriteLock(ApplicationId appId, LockName name) Get write lock object.
void	deleteLock(Lock lock) Delete a lock create using any of the create lock methods above.
List<Lock>	getAppLocks(ApplicationId appId) Get the list of locks Lock that are created by the specified application instance.
List<Lock>	getAppLocks(List<LockName> lockNameList, ApplicationId appId) Get the list of locks Lock present on the specified set of lockInfos that were created by the provided application instance.

Method Detail

createReadLock

Lock createReadLock(ApplicationId appId,
                  LockName name)

Get read lock object. This lock is "Shared" in nature. More than one read lock can be acquired on the same lockName.

Parameters:

appId - Application Id [ appName and instanceId ]

name - Lock name hierarchy [ Ex: new LockName("appName", "tbl", "key1") ]

Returns:

Lock created read lock object

createWriteLock

Lock createWriteLock(ApplicationId appId,
                   LockName name)

Get write lock object. This lock is "Exclusive" in nature. To acquire a write lock, no other lock should be in held state on the lockname.

Parameters:

appId - Application Id [ appName and instanceId ]

name - Lock name hierarchy [ Ex: new LockName("appName", "tbl", "key1") ]

Returns:

Lock created write lock object

createMultiLock

Lock createMultiLock(ApplicationId appId,
                   LockName name,
                   List<LockNameType> locks)
                     throws LockServiceException.LockMaxCountExceededException,
                            LockServiceException.LockAlreadyCreatedException,
                            LockServiceException.LockListMismatchException,
                            ServiceNotAvailableException,
                            IOException,
                            InterruptedException

Create a lock object that represents a pool of locks requested. Locks list can contain a set of read and/or write locks. All the pooled locks can be acquired and/or released in a single go. Currently locking subsystem doesn't provide any help for deadlock prevention. Application need to wisely create and acquire the multilock so that it wouldn't result in a deadlock situation. Note that there can be a maximum of 100 locks that can be added to the multi lock.

Parameters:

appId - Application Id [ appName and instanceId ]

name - Unique name of the lock. This can be used to uniquely identify name of the lock pool

locks - List of locks

Returns:

Lock created multi lock object

Throws:

LockServiceException.LockMaxCountExceededException - Locks count exceeded limit

LockServiceException.LockAlreadyCreatedException - lock already created by app instance

LockServiceException.LockListMismatchException - Lock list mismatch with existing lock

ServiceNotAvailableException - Lock service is down

InterruptedException - Operation interrupted exception

IOException - IO exception while data serialization

deleteLock

void deleteLock(Lock lock)
                throws ServiceNotAvailableException,
                       InterruptedException

Delete a lock create using any of the create lock methods above.

Parameters:

lock - Lock to be delete

Throws:

ServiceNotAvailableException - Lock service is down

InterruptedException - Operation interrupted exception

getAppLocks

List<Lock> getAppLocks(List<LockName> lockNameList,
                     ApplicationId appId)
                       throws ServiceNotAvailableException,
                              InterruptedException

Get the list of locks Lock present on the specified set of lockInfos that were created by the provided application instance. Input parameter lockList can contain a set of {APP, Key} combination and/or {APP} alone. In case of {APP, Key}, all the locks of the specified application instance are retrieved that are on the key {Key} specified. In case of {APP}, all the locks on keys under {APP} are retrieved that are created by the specified application instance. On getting the Lock list, Application is supposed to understand current state Lock.getState() of each Lock Lock and act on it. This method shall be used when an application instance dies and another instance takes over the control. The latter application would take the locks owned by the crashed application instance and act on them.

Parameters:

lockNameList - List of LockName objects. The list contains the list of lock hierarchy to be searched that were owned by the provided application instance. All type [read/write/multi] of locks that are owned by the application instance are fetched by the query.

appId - Lock owning Application identifier

Returns:

list of Locks

Throws:

ServiceNotAvailableException - Lock service is down

InterruptedException - Operation interrupted exception

getAppLocks

List<Lock> getAppLocks(ApplicationId appId)
                       throws ServiceNotAvailableException,
                              InterruptedException

Get the list of locks Lock that are created by the specified application instance. Note: This is a time consuming operation. It is suggested to use another variant of the API that takes the LockNameType list to search for the application owning locks. On getting the Lock list, Application is supposed to understand current state Lock.getState() of each Lock Lock and act on it. This method shall be used when an application instance dies and another instance takes over the control. The latter application would take the locks owned by the crashed application instance and act on them.

Parameters:

appId - Lock owning Application identifier

Returns:

list of Locks

Throws:

ServiceNotAvailableException - Lock service is down

InterruptedException - Operation interrupted exception

changeOwner

boolean changeOwner(Lock lock,
                  ApplicationId appId)
                    throws ServiceNotAvailableException,
                           InterruptedException,
                           IOException

Change the ownership of a set of read and/or write locks. This method shall be used when an application instance wants to take over the locks of failed application instance. If the owner of the lock changed without the owner instance failure, it may result in losing track of the lock when it is queried after a instance failure.

Parameters:

lock - lock whose ownership needs to be changed

appId - New owner Application identifier

Returns:

true if operation succeeds false otherwise

Throws:

ServiceNotAvailableException - Lock service is down

InterruptedException - Operation interrupted exception

IOException - IO exception while data serialization