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

Copyright © 2014. All Rights Reserved.