com.amazonaws.services.dynamodbv2

Class MomentoDynamoDBLockClient

java.lang.Object

com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

com.amazonaws.services.dynamodbv2.MomentoDynamoDBLockClient

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Runnable

public class MomentoDynamoDBLockClient
extends com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient
implements java.io.Closeable

Provides a simple library for using DynamoDB's consistent read/write feature to use it for managing distributed locks.

In order to use this library, the client must create a cache in Momento, although the library provides a convenience method for creating that cache (createLockCache.)

Here is some example code for how to use the lock client for leader election to work on a resource called "host-2" (it assumes you already have a Momento cache named lockCache, which can be created with the createLockCache helper method):

 
  AmazonDynamoDBLockClient lockClient = new MomentoDynamoDBLockClient(
      MomentoDynamoDBLockClientOptions.builder(dynamoDBClient, "lockTable").build();
  try {
      // Attempt to acquire the lock indefinitely, polling Momento every 2 seconds for the lock
      LockItem lockItem = lockClient.acquireLock(
          AcquireLockOptions.builder("host-2")
              .withRefreshPeriod(120L)
              .withAdditionalTimeToWaitForLock(Long.MAX_VALUE / 2L)
              .withTimeUnit(TimeUnit.MILLISECONDS)
              .build());
      if (!lockItem.isExpired()) {
          // do business logic, you can call lockItem.isExpired() to periodically check to make sure you still have the lock
          // the background thread will keep the lock valid for you by sending heartbeats (default is every 5 seconds)
      }
  } catch (LockNotGrantedException x) {
      // Should only be thrown if the lock could not be acquired for Long.MAX_VALUE / 2L milliseconds.
  }
 
 

Field Summary

Fields inherited from class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

ACQUIRE_LOCK_THAT_DOESNT_EXIST_PK_CONDITION, ACQUIRE_LOCK_THAT_DOESNT_EXIST_PK_SK_CONDITION, DATA, DATA_PATH_EXPRESSION_VARIABLE, DATA_VALUE_EXPRESSION_VARIABLE, dynamoDB, IS_RELEASED, IS_RELEASED_ATTRIBUTE_VALUE, IS_RELEASED_INDICATOR, IS_RELEASED_PATH_EXPRESSION_VARIABLE, IS_RELEASED_VALUE, IS_RELEASED_VALUE_EXPRESSION_VARIABLE, LEASE_DURATION, LEASE_DURATION_PATH_VALUE_EXPRESSION_VARIABLE, LEASE_DURATION_VALUE_EXPRESSION_VARIABLE, lockClientId, NEW_RVN_VALUE_EXPRESSION_VARIABLE, OWNER_NAME, OWNER_NAME_PATH_EXPRESSION_VARIABLE, OWNER_NAME_VALUE_EXPRESSION_VARIABLE, PK_EXISTS_AND_IS_RELEASED_CONDITION, PK_EXISTS_AND_OWNER_NAME_SAME_AND_RVN_SAME_CONDITION, PK_EXISTS_AND_RVN_IS_THE_SAME_AND_IS_RELEASED_CONDITION, PK_EXISTS_AND_RVN_IS_THE_SAME_CONDITION, PK_EXISTS_AND_SK_EXISTS_AND_IS_RELEASED_CONDITION, PK_EXISTS_AND_SK_EXISTS_AND_OWNER_NAME_SAME_AND_RVN_SAME_CONDITION, PK_EXISTS_AND_SK_EXISTS_AND_RVN_IS_THE_SAME_AND_IS_RELEASED_CONDITION, PK_EXISTS_AND_SK_EXISTS_AND_RVN_IS_THE_SAME_CONDITION, PK_PATH_EXPRESSION_VARIABLE, PK_VALUE_EXPRESSION_VARIABLE, QUERY_PK_EXPRESSION, RECORD_VERSION_NUMBER, REMOVE_IS_RELEASED_UPDATE_EXPRESSION, RVN_PATH_EXPRESSION_VARIABLE, RVN_VALUE_EXPRESSION_VARIABLE, SK_PATH_EXPRESSION_VARIABLE, tableName, UPDATE_IS_RELEASED, UPDATE_IS_RELEASED_AND_DATA, UPDATE_LEASE_DURATION_AND_RVN, UPDATE_LEASE_DURATION_AND_RVN_AND_DATA, UPDATE_LEASE_DURATION_AND_RVN_AND_REMOVE_DATA

Constructor Summary

Constructors

Constructor and Description
MomentoDynamoDBLockClient(MomentoDynamoDBLockClientOptions lockClientOptions)

Method Summary

Modifier and Type	Method and Description
com.amazonaws.services.dynamodbv2.LockItem	acquireLock(com.amazonaws.services.dynamodbv2.AcquireLockOptions options) Attempts to acquire a lock until it either acquires the lock, or a specified additionalTimeToWaitForLock is reached.
void	close()
void	createLockCache(java.lang.String cacheName)
java.util.stream.Stream<com.amazonaws.services.dynamodbv2.LockItem>	getAllLocksFromDynamoDB(boolean deleteOnRelease)
java.util.Optional<com.amazonaws.services.dynamodbv2.LockItem>	getLock(java.lang.String key, java.util.Optional<java.lang.String> sortKey) Finds out who owns the given lock, but does not acquire the lock.
java.util.stream.Stream<com.amazonaws.services.dynamodbv2.LockItem>	getLocksByPartitionKey(java.lang.String key, boolean deleteOnRelease)
boolean	hasLock(java.lang.String key, java.util.Optional<java.lang.String> sortKey) Returns true if the client currently owns the lock with @param key and @param sortKey.
boolean	lockCacheExists() Checks whether the lock cache exists in Momento.
boolean	lockTableExists() Checks whether the lock cache exists in Momento.
boolean	releaseLock(com.amazonaws.services.dynamodbv2.LockItem item) Releases the given lock if the current user still has it, returning true if the lock was successfully released, and false if someone else already stole the lock.
boolean	releaseLock(com.amazonaws.services.dynamodbv2.ReleaseLockOptions options)
void	sendHeartbeat(com.amazonaws.services.dynamodbv2.LockItem lockItem) Sends a heartbeat to indicate that the given lock is still being worked on.
void	sendHeartbeat(com.amazonaws.services.dynamodbv2.SendHeartbeatOptions options)
java.util.Optional<com.amazonaws.services.dynamodbv2.LockItem>	tryAcquireLock(com.amazonaws.services.dynamodbv2.AcquireLockOptions options) Attempts to acquire lock.

Methods inherited from class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

assertLockTableExists, createLockTableInDynamoDB, getLockFromDynamoDB, run

Methods inherited from class java.lang.Object

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

Constructor Detail

MomentoDynamoDBLockClient

public MomentoDynamoDBLockClient(MomentoDynamoDBLockClientOptions lockClientOptions)

Method Detail

getAllLocksFromDynamoDB

public java.util.stream.Stream<com.amazonaws.services.dynamodbv2.LockItem> getAllLocksFromDynamoDB(boolean deleteOnRelease)

Overrides:

getAllLocksFromDynamoDB in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

getLocksByPartitionKey

public java.util.stream.Stream<com.amazonaws.services.dynamodbv2.LockItem> getLocksByPartitionKey(java.lang.String key,
                                                                                                  boolean deleteOnRelease)

Overrides:

getLocksByPartitionKey in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

createLockCache

public void createLockCache(java.lang.String cacheName)

acquireLock

public com.amazonaws.services.dynamodbv2.LockItem acquireLock(com.amazonaws.services.dynamodbv2.AcquireLockOptions options)
                                                       throws com.amazonaws.services.dynamodbv2.model.LockNotGrantedException,
                                                              java.lang.InterruptedException

Attempts to acquire a lock until it either acquires the lock, or a specified additionalTimeToWaitForLock is reached. This method will poll Momento based on the refreshPeriod. If it does not see the lock in Momento, it will immediately return the lock to the caller. If it does see the lock, it waits for as long as additionalTimeToWaitForLock without acquiring the lock, then it will throw a LockNotGrantedException.

Note that this method will wait for at least as long as the leaseDuration in order to acquire a lock that already exists. If the lock is not acquired in that time, it will wait an additional amount of time specified in additionalTimeToWaitForLock before giving up.

See the defaults set when constructing a new AcquireLockOptions object for any fields that you do not set explicitly.

Overrides:

acquireLock in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Parameters:

options - A combination of optional arguments that may be passed in for acquiring the lock

Returns:

the lock

Throws:

java.lang.InterruptedException - in case the Thread.sleep call was interrupted while waiting to refresh.

com.amazonaws.services.dynamodbv2.model.LockNotGrantedException

hasLock

public boolean hasLock(java.lang.String key,
                       java.util.Optional<java.lang.String> sortKey)

Returns true if the client currently owns the lock with @param key and @param sortKey. It returns false otherwise.

Overrides:

hasLock in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Parameters:

key - The partition key representing the lock.

sortKey - The sort key if present.

Returns:

true if the client owns the lock. It returns false otherwise.

lockTableExists

public boolean lockTableExists()

Checks whether the lock cache exists in Momento.

Overrides:

lockTableExists in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Returns:

true if the cache exists, false otherwise.

lockCacheExists

public boolean lockCacheExists()

Checks whether the lock cache exists in Momento.

Returns:

true if the cache exists, false otherwise.

tryAcquireLock

public java.util.Optional<com.amazonaws.services.dynamodbv2.LockItem> tryAcquireLock(com.amazonaws.services.dynamodbv2.AcquireLockOptions options)
                                                                              throws java.lang.InterruptedException

Attempts to acquire lock. If successful, returns the lock. Otherwise, returns Optional.empty(). For more details on behavior, please see acquireLock.

Overrides:

tryAcquireLock in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Parameters:

options - The options to use when acquiring the lock.

Returns:

the lock if successful.

Throws:

java.lang.InterruptedException - in case this.acquireLock was interrupted.

getLock

public java.util.Optional<com.amazonaws.services.dynamodbv2.LockItem> getLock(java.lang.String key,
                                                                              java.util.Optional<java.lang.String> sortKey)

Finds out who owns the given lock, but does not acquire the lock. It returns the metadata currently associated with the given lock. If the client currently has the lock, it will return the lock, and operations such as releaseLock will work. However, if the client does not have the lock, then operations like releaseLock will not work (after calling getLock, the caller should check lockItem.isExpired() to figure out if it currently has the lock.)

Overrides:

getLock in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Parameters:

key - The partition key representing the lock.

sortKey - The sort key if present.

Returns:

A LockItem that represents the lock, if the lock exists.

releaseLock

public boolean releaseLock(com.amazonaws.services.dynamodbv2.LockItem item)

Releases the given lock if the current user still has it, returning true if the lock was successfully released, and false if someone else already stole the lock. Deletes the lock item if it is released and deleteLockItemOnClose is set.

Overrides:

releaseLock in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Parameters:

item - The lock item to release

Returns:

true if the lock is released, false otherwise

releaseLock

public boolean releaseLock(com.amazonaws.services.dynamodbv2.ReleaseLockOptions options)

Overrides:

releaseLock in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

sendHeartbeat

public void sendHeartbeat(com.amazonaws.services.dynamodbv2.LockItem lockItem)

Sends a heartbeat to indicate that the given lock is still being worked on. If using createHeartbeatBackgroundThread=true when setting up this object, then this method is unnecessary, because the background thread will be periodically calling it and sending heartbeats. However, if createHeartbeatBackgroundThread=false, then this method must be called to instruct Momento that the lock should not be expired.

The lease duration of the lock will be set to the default specified in the constructor of this class.

Overrides:

sendHeartbeat in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Parameters:

lockItem - the lock item row to send a heartbeat and extend lock expiry.

sendHeartbeat

public void sendHeartbeat(com.amazonaws.services.dynamodbv2.SendHeartbeatOptions options)

Overrides:

sendHeartbeat in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class com.amazonaws.services.dynamodbv2.AmazonDynamoDBLockClient

Throws:

java.io.IOException