com.thinkaurelius.titan.diskstorage.locking

## Class AbstractLocker<S extends LockStatus>

- java.lang.Object
- - com.thinkaurelius.titan.diskstorage.locking.AbstractLocker<S>

- Type Parameters:
    `S` - An implementation-specific type holding information about a single lock; see `ConsistentKeyLockStatus` for an example
  All Implemented Interfaces:
    Locker
  Direct Known Subclasses:
    ConsistentKeyLocker

      public abstract class AbstractLocker<S extends LockStatus>
      extends Object
      implements Locker

  Abstract base class for building lockers. Implements locking between threads using `LocalLockMediator` but delegates inter-process lock resolution to its subclasses.
  See Also:
    `ConsistentKeyLocker`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `AbstractLocker.Builder<S,B extends AbstractLocker.Builder<S,B>>` Abstract builder for this Locker implementation.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected LocalLockMediator<StoreTransaction>` | `llm` Resolves lock contention by multiple threads.
    `protected Duration` | `lockExpire` The amount of time, in `times``.getUnit()`, that may pass after writing a lock before it is considered to be invalid and automatically unlocked.
    `protected LockerState<S>` | `lockState` Stores all information about all locks this implementation has taken on behalf of any `StoreTransaction`.
    `protected org.slf4j.Logger` | `log`
    `protected StaticBuffer` | `rid` Uniquely identifies a process within a domain (or across all domains, though only intra-domain uniqueness is required)
    `protected ConsistentKeyLockerSerializer` | `serializer` This is sort-of Cassandra/HBase specific.
    `protected TimestampProvider` | `times` Sole source of time.
    `protected TimeUnit` | `timeUnit` This is a copy of `times.getUnit()`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractLocker(StaticBuffer rid, TimestampProvider times, ConsistentKeyLockerSerializer serializer, LocalLockMediator<StoreTransaction> llm, LockerState<S> lockState, Duration lockExpire, org.slf4j.Logger log)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkLocks(StoreTransaction tx)` Verify that all previous `Locker.writeLock(KeyColumn, StoreTransaction)` calls with `tx` actually succeeded.
    `protected abstract void` | `checkSingleLock(KeyColumn lockID, S lockStatus, StoreTransaction tx)` Try to verify that the lock identified by `lockID` is already held by `tx`.
    `void` | `deleteLocks(StoreTransaction tx)` Release every lock currently held by `tx`.
    `protected abstract void` | `deleteSingleLock(KeyColumn lockID, S lockStatus, StoreTransaction tx)` Try to unlock/release/delete the lock identified by `lockID` and both held by and verified for `tx`.
    `void` | `writeLock(KeyColumn lockID, StoreTransaction tx)` Attempt to acquire/take/claim/write the lock named by `lockID`.
    `protected abstract S` | `writeSingleLock(KeyColumn lockID, StoreTransaction tx)` Try to take/acquire/write/claim a lock uniquely identified within this `Locker` by the `lockID` argument on behalf of `tx`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### rid

          protected final StaticBuffer rid

      Uniquely identifies a process within a domain (or across all domains, though only intra-domain uniqueness is required)

    - #### times

          protected final TimestampProvider times

      Sole source of time. All fields of type long that represent times or durations should be expressed in terms of `TimestampProvider.getUnit()`. Furthermore, if the locking backend allows the client to set a timestamp on writes, those timestamps should be in the same units.

      Don't call `System.currentTimeMillis()` or `System.nanoTime()` directly. Use only this object. This object is replaced with a mock during testing to give tests exact control over the flow of time.

    - #### timeUnit

          protected final TimeUnit timeUnit

      This is a copy of `times.getUnit()`. This field shouldn't exist. The JIT will undoubtedly inline `getUnit()` so this just wastes space and duplicates information. It's only here to ease testing with EasyMock. By calling `getUnit()` only during construction and never during normal operation, it's easier to create a strict method-order-checking mock of TimestampProvider in testing.

    - #### serializer

          protected final ConsistentKeyLockerSerializer serializer

      This is sort-of Cassandra/HBase specific. It concatenates `KeyColumn` arguments into a single StaticBuffer containing the key followed by the column and vice-versa.

    - #### llm

          protected final LocalLockMediator<StoreTransaction> llm

      Resolves lock contention by multiple threads.

    - #### lockState

          protected final LockerState<S extends LockStatus> lockState

      Stores all information about all locks this implementation has taken on behalf of any `StoreTransaction`. It is parameterized in a type specific to the concrete subclass, so that concrete implementations can store information specific to their locking primitives.

    - #### lockExpire

          protected final Duration lockExpire

      The amount of time, in `times``.getUnit()`, that may pass after writing a lock before it is considered to be invalid and automatically unlocked.

    - #### log

          protected final org.slf4j.Logger log

  - ### Constructor Detail

    - #### AbstractLocker

          public AbstractLocker(StaticBuffer rid,
                        TimestampProvider times,
                        ConsistentKeyLockerSerializer serializer,
                        LocalLockMediator<StoreTransaction> llm,
                        LockerState<S> lockState,
                        Duration lockExpire,
                        org.slf4j.Logger log)

  - ### Method Detail

    - #### writeSingleLock

          protected abstract S writeSingleLock(KeyColumn lockID,
                          StoreTransaction tx)
                                                           throws Throwable

      Try to take/acquire/write/claim a lock uniquely identified within this `Locker` by the `lockID` argument on behalf of `tx`.
      Parameters:
        `lockID` - identifies the lock
        `tx` - identifies the process claiming this lock
      Returns:
        a `LockStatus` implementation on successful lock aquisition
      Throws:
        `Throwable` - if the lock could not be taken/acquired/written/claimed or the attempted write encountered an error

    - #### checkSingleLock

          protected abstract void checkSingleLock(KeyColumn lockID,
                             S lockStatus,
                             StoreTransaction tx)
                                           throws Throwable

      Try to verify that the lock identified by `lockID` is already held by `tx`. The `lockStatus` argument refers to the object returned by a previous call to `writeSingleLock(KeyColumn, StoreTransaction)`. This should be a read-only operation: return if the lock is already held, but this method finds that it is not held, then throw an exception instead of trying to acquire it.

      This method is only useful with nonblocking locking implementations try to lock and then check the outcome of the attempt in two separate stages. For implementations that build `writeSingleLock(...)` on a synchronous locking primitive, such as a blocking `lock()` method or a blocking semaphore `p()`, this method is redundant with `writeSingleLock(...)` and may unconditionally return true.
      Parameters:
        `lockID` - identifies the lock to check
        `lockStatus` - the result of a prior successful `writeSingleLock(...)` call on this `lockID` and `tx`
        `tx` - identifies the process claiming this lock
      Throws:
        `Throwable` - if the lock fails the check or if the attempted check encountered an error

    - #### deleteSingleLock

          protected abstract void deleteSingleLock(KeyColumn lockID,
                              S lockStatus,
                              StoreTransaction tx)
                                            throws Throwable

      Try to unlock/release/delete the lock identified by `lockID` and both held by and verified for `tx`. This method is only called with arguments for which `writeSingleLock(KeyColumn, StoreTransaction)` and `checkSingleLock(KeyColumn, LockStatus, StoreTransaction)` both returned successfully (i.e. without exceptions).
      Parameters:
        `lockID` - identifies the lock to release
        `lockStatus` - the result of a prior successful `writeSingleLock(...)` followed by a successful `checkSingleLock(...)`
        `tx` - identifies the process that wrote and checked this lock
      Throws:
        `Throwable` - if the lock could not be released/deleted or if the attempted delete encountered an error

    - #### writeLock

          public void writeLock(KeyColumn lockID,
                       StoreTransaction tx)
                         throws TemporaryLockingException,
                                PermanentLockingException

      Description copied from interface: `Locker`
      Attempt to acquire/take/claim/write the lock named by `lockID`.

      Returns on success and throws an exception on failure.

      Specified by:
        `writeLock` in interface `Locker`
      Parameters:
        `lockID` - the lock to acquire
        `tx` - the transaction attempting to acquire the lock
      Throws:
        `TemporaryLockingException` - a failure likely to disappear if the call is retried
        `PermanentLockingException` - a failure unlikely to disappear if the call is retried

    - #### checkLocks

          public void checkLocks(StoreTransaction tx)
                          throws TemporaryLockingException,
                                 PermanentLockingException

      Description copied from interface: `Locker`
      Verify that all previous `Locker.writeLock(KeyColumn, StoreTransaction)` calls with `tx` actually succeeded.

      Returns on success and throws an exception on failure.

      Specified by:
        `checkLocks` in interface `Locker`
      Parameters:
        `tx` - the transaction attempting to check the result of previous `writeLock(..., tx)` calls in which it was the `tx` argument
      Throws:
        `TemporaryLockingException` - a failure likely to disappear if the call is retried
        `PermanentLockingException` - a failure unlikely to disappear if the call is retried

    - #### deleteLocks

          public void deleteLocks(StoreTransaction tx)
                           throws TemporaryLockingException,
                                  PermanentLockingException

      Description copied from interface: `Locker`
      Release every lock currently held by `tx`.

      Returns on success and throws an exception on failure.

      Specified by:
        `deleteLocks` in interface `Locker`
      Parameters:
        `tx` - the transaction attempting to delete locks taken in previous `writeLock(..., tx)` calls in which it was the `tx` argument
      Throws:
        `TemporaryLockingException` - a failure likely to disappear if the call is retried
        `PermanentLockingException` - a failure unlikely to disappear if the call is retried

Copyright © 2012–2014. All rights reserved.