com.atlassian.beehive.db.spi

Interface ClusterLockDao

public interface ClusterLockDao

Provides access to the Cluster Lock DB table. Clustered applications need to implement this DAO in order to be able to use the DatabaseClusterLockService.

Method Summary

Modifier and Type	Method and Description
void	deleteLocksHeldByNode(String nodeId) Deletes any locks held by the given node.
List<ClusterLockStatus>	getAllHeldClusterLocks() Returns lock details for all cluster locks being held by any node.
ClusterLockStatus	getClusterLockStatusByName(String lockName) Returns the cluster lock details for the given name, or null if no such lock has ever been created.
void	insertEmptyClusterLock(String lockName, long updateTime) Attempt to insert an "unlocked" DB row for the named lock.
boolean	tryUpdateAcquireLock(String lockName, String nodeId, long updateTime) Attempt to acquire an existing named lock for the given nodeId.
void	unlock(String lockName, String nodeId, long updateTime) Unlock the named lock, if this node still holds the lock.

Method Detail

getAllHeldClusterLocks

@Nonnull
List<ClusterLockStatus> getAllHeldClusterLocks()

Returns lock details for all cluster locks being held by any node.

Returns:

a list of cluster lock details for all locks held by any node, or an empty list if no such locks exist.

getClusterLockStatusByName

@Nullable
ClusterLockStatus getClusterLockStatusByName(@Nonnull
                                                       String lockName)

Returns the cluster lock details for the given name, or null if no such lock has ever been created.

Parameters:

lockName - the globally unique id of the lock

Returns:

the cluster lock details for the given name, or null if no such lock has ever been created.

tryUpdateAcquireLock

boolean tryUpdateAcquireLock(@Nonnull
                             String lockName,
                             @Nonnull
                             String nodeId,
                             long updateTime)

Attempt to acquire an existing named lock for the given nodeId.

This should be an UPDATE ... WHERE operation like

 UPDATE CLUSTER_LOCK
   SET LOCKED_BY_NODE = ?
   WHERE LOCK_NAME = ?
   AND LOCKED_BY_NODE IS NULL
 

• If the lock is obtained successfully (ie 1 row was updated), this method returns true.
• If the lock could not be obtained (ie 0 rows were updated), this method returns false.
  (we even fail if the holder of the lock is this node, because it could be locked by another thread.)

Parameters:

lockName - the globally unique id of the lock

nodeId - This node's ID

updateTime - the time in milliseconds that this update was written

Returns:

true if we acquired the lock, false if the row exists but is already locked.

insertEmptyClusterLock

void insertEmptyClusterLock(@Nonnull
                            String lockName,
                            long updateTime)

Attempt to insert an "unlocked" DB row for the named lock. (That is, the "locked by" column should be NULL).

You can assume that the lock name is not null. This insert should only insert a single row for the given lock name (which will never be null). This is expected to be achieved simply by putting a unique constraint on the LOCK_NAME column.

If the row already exists, then this method must catch the unique constraint violation and terminate normally. All other SQL errors should be thrown as a RuntimeException of some kind.

Parameters:

lockName - the lock identifier

updateTime - the time in milliseconds that this insert was written

unlock

void unlock(@Nonnull
            String lockName,
            @Nonnull
            String nodeId,
            long updateTime)

Unlock the named lock, if this node still holds the lock.

If for some reason we no longer hold the lock then we should not unlock it. That is, the SQL should look something like

 UPDATE CLUSTER_LOCK
   SET LOCKED_BY_NODE = NULL
   WHERE LOCK_NAME = ?
   AND LOCKED_BY_NODE = ?
 

Parameters:

lockName - the lock identifier

nodeId - This node's ID

updateTime - the time in milliseconds that this update was written

deleteLocksHeldByNode

void deleteLocksHeldByNode(String nodeId)

Deletes any locks held by the given node. In a non-clustered environment, this will be the only instance.

Parameters:

nodeId - the node for which to delete the locks

Since:

1.0