Module dk.cloudcreate.essentials.components.foundation
Package dk.cloudcreate.essentials.components.foundation.fencedlock

Interface FencedLockManager

All Superinterfaces:
Lifecycle
All Known Implementing Classes:
DBFencedLockManager
public interface FencedLockManager extends Lifecycle
This library provides a Distributed Locking Manager based of the Fenced Locking concept described here

The FencedLockManager is responsible for obtaining and managing distributed FencedLock's, which are named exclusive locks.
Only one FencedLockManager instance can acquire a FencedLock at a time.
The implementation has been on supporting intra-service (i.e. across different deployed instances of the same service) Lock support through database based implementations (MongoFencedLockManager and PostgresqlFencedLockManager).
In a service oriented architecture it's common for all deployed instances of a given service (e.g. a Sales service) to share the same underlying database(s). As long as the different deployed (Sales) services instances can share the same underlying database, then you use the FencedLockManager concept for handling distributed locks across all deployed (Sales service) instances in the cluster.
If you need cross-service lock support, e.g. across instances of different services (such as across Sales, Billing and Shipping services), then you need to use a dedicated distributed locking service such as Zookeeper.

To coordinate this properly it's important that each getLockManagerInstanceId() is unique across the cluster.
Per default, it uses the local machine hostname as getLockManagerInstanceId() value.

  • Method Details

    • lookupLock

      Optional<FencedLock> lookupLock(LockName lockName)
      Lookup a lock
      Parameters:
      lockName - the name of the lock
      Returns:
      an Optional with the locks current state or Optional.empty() if the lock doesn't exist

    • tryAcquireLock

      Optional<FencedLock> tryAcquireLock(LockName lockName)
      Try to acquire the lock using this Lock Manager instance
      Parameters:
      lockName - the name of the lock
      Returns:
      An Optional with the FencedLock IF it was acquired by the FencedLockManager on this JVM Node, otherwise it return an empty Optional

    • tryAcquireLock

      Optional<FencedLock> tryAcquireLock(LockName lockName, Duration timeout)
      Try to acquire the lock on this JVM Node
      Parameters:
      lockName - the name of the lock
      timeout - timeout for the lock acquiring
      Returns:
      An Optional with the FencedLock IF it was acquired by the FencedLockManager on this JVM Node, otherwise it return an empty Optional

    • acquireLock

      FencedLock acquireLock(LockName lockName)
      Acquire the lock on this JVM Node. If the lock already is acquired by another JVM Node, then this method will wait until the lock can be acquired by this JVM node
      Parameters:
      lockName - the name of the lock
      Returns:
      The FencedLock when can be acquired by this JVM Node

    • isLockAcquired

      boolean isLockAcquired(LockName lockName)
      Is the lock acquired
      Parameters:
      lockName - the name of the lock
      Returns:
      true if the lock is acquired, otherwise false

    • isLockedByThisLockManagerInstance

      boolean isLockedByThisLockManagerInstance(LockName lockName)
      Is the lock already acquired by this JVM node
      Parameters:
      lockName - the lock name
      Returns:
      true of the lock is acquired by this JVM node

    • isLockAcquiredByAnotherLockManagerInstance

      boolean isLockAcquiredByAnotherLockManagerInstance(LockName lockName)
      Is the lock already acquired by another JVM node
      Parameters:
      lockName - the name of the lock
      Returns:
      true of the lock is acquired by this JVM node

    • acquireLockAsync

      void acquireLockAsync(LockName lockName, LockCallback lockCallback)
      Asynchronously try to acquire a lock by the given name and call the LockCallback.lockAcquired(FencedLock) when the lock is acquired
      To stop the background acquiring process, you need to call cancelAsyncLockAcquiring(LockName) with the same lockName
      Parameters:
      lockName - the name of the lock
      lockCallback - the callback that's notified when a lock is acquired

    • cancelAsyncLockAcquiring

      void cancelAsyncLockAcquiring(LockName lockName)
      Cancel a previously started asynchronous lock acquiring background process
      IF this JVM node had acquired a FencedLock then this lock will be released AND the LockCallback.lockReleased(FencedLock) will be called on the LockCallback instance that was supplied to the acquireLockAsync(LockName, LockCallback)
      Otherwise only the background lock acquiring process will be stopped.
      Parameters:
      lockName - the name of the lock

    • getLockManagerInstanceId

      String getLockManagerInstanceId()
      Get the instance id that distinguishes different FencedLockManager instances from each other
      For local JVM testing you can assign a unique instance id to allow multiple FencedLockManager's to compete for Locks.
      In production the hostname should be returned
      Returns:
      the instance id