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 Summary

Modifier and Type	Method	Description
FencedLock	acquireLock(LockName lockName)	Acquire the lock on this JVM Node.
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
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.
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
boolean	isLockAcquired(LockName lockName)	Is the lock acquired
boolean	isLockAcquiredByAnotherLockManagerInstance(LockName lockName)	Is the lock already acquired by another JVM node
boolean	isLockedByThisLockManagerInstance(LockName lockName)	Is the lock already acquired by this JVM node
Optional<FencedLock>	lookupLock(LockName lockName)	Lookup a lock
Optional<FencedLock>	tryAcquireLock(LockName lockName)	Try to acquire the lock using this Lock Manager instance
Optional<FencedLock>	tryAcquireLock(LockName lockName, Duration timeout)	Try to acquire the lock on this JVM Node

Methods inherited from interface dk.cloudcreate.essentials.components.foundation.Lifecycle

isStarted, start, stop

Method Detail

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