com.amazonaws.services.dynamodbv2

Class AcquireLockOptions.AcquireLockOptionsBuilder

java.lang.Object

com.amazonaws.services.dynamodbv2.AcquireLockOptions.AcquireLockOptionsBuilder

Enclosing class:

AcquireLockOptions

public static class AcquireLockOptions.AcquireLockOptionsBuilder
extends Object

A builder for setting up an AcquireLockOptions object. This allows clients to configure their settings when calling acquireLock(). The only required parameter is the partitionKey for the lock.

Method Summary

Modifier and Type	Method and Description
AcquireLockOptions	build()
String	toString()
AcquireLockOptions.AcquireLockOptionsBuilder	withAcquireOnlyIfLockAlreadyExists(Boolean acquireOnlyIfLockAlreadyExists) Sets whether or not to allow acquiring locks if the lock does not exist already
AcquireLockOptions.AcquireLockOptionsBuilder	withAcquireReleasedLocksConsistently(boolean acquireReleasedLocksConsistently) With this being true, the lock client will ensure that released locks are acquired consistently in order to preserve existing lock data in dynamodb.
AcquireLockOptions.AcquireLockOptionsBuilder	withAdditionalAttributes(Map<String,software.amazon.awssdk.services.dynamodb.model.AttributeValue> additionalAttributes) Stores some additional attributes with each lock.
AcquireLockOptions.AcquireLockOptionsBuilder	withAdditionalTimeToWaitForLock(Long additionalTimeToWaitForLock)
AcquireLockOptions.AcquireLockOptionsBuilder	withData(ByteBuffer data) Sets data to be stored alongside the lock
AcquireLockOptions.AcquireLockOptionsBuilder	withDeleteLockOnRelease(Boolean deleteLockOnRelease)
AcquireLockOptions.AcquireLockOptionsBuilder	withReentrant(boolean reentrant) With this set to true, the lock client will check first if it already owns the lock.
AcquireLockOptions.AcquireLockOptionsBuilder	withRefreshPeriod(Long refreshPeriod)
AcquireLockOptions.AcquireLockOptionsBuilder	withReplaceData(Boolean replaceData) Sets whether or not to replace any existing lock data with the data parameter.
AcquireLockOptions.AcquireLockOptionsBuilder	withSessionMonitor(long safeTimeWithoutHeartbeat, Optional<Runnable> sessionMonitorCallback) Registers a "SessionMonitor."
AcquireLockOptions.AcquireLockOptionsBuilder	withShouldSkipBlockingWait(boolean shouldSkipBlockingWait) With this being true, the lock client will not block the running thread and wait for lock, rather will fast fail the request, so that the caller can either choose to back-off and process the same request or start processing a new request.
AcquireLockOptions.AcquireLockOptionsBuilder	withSortKey(String sortKey)
AcquireLockOptions.AcquireLockOptionsBuilder	withTimeUnit(TimeUnit timeUnit)
AcquireLockOptions.AcquireLockOptionsBuilder	withUpdateExistingLockRecord(Boolean updateExistingLockRecord) With this being true lock client will only update the current lock record if present otherwise create a new one.

Methods inherited from class java.lang.Object

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

Method Detail

withSortKey

public AcquireLockOptions.AcquireLockOptionsBuilder withSortKey(String sortKey)

Parameters:

sortKey - The sort key to try and acquire the lock on (specify if and only if the table has sort keys.)

Returns:

a reference to this builder for fluent method chaining

withData

public AcquireLockOptions.AcquireLockOptionsBuilder withData(ByteBuffer data)

Sets data to be stored alongside the lock

Parameters:

data - Any data that needs to be stored alongside the lock (can be null if no data is needed to be stored there. If null with replaceData = true, the data will be removed)

Returns:

a reference to this builder for fluent method chaining

withReplaceData

public AcquireLockOptions.AcquireLockOptionsBuilder withReplaceData(Boolean replaceData)

Sets whether or not to replace any existing lock data with the data parameter.

Parameters:

replaceData - If true, this will replace the lock data currently stored alongside the lock.

Returns:

a reference to this builder for fluent method chaining

withDeleteLockOnRelease

public AcquireLockOptions.AcquireLockOptionsBuilder withDeleteLockOnRelease(Boolean deleteLockOnRelease)

Parameters:

deleteLockOnRelease - Whether or not the lock should be deleted when close() is called on the resulting LockItem

Returns:

a reference to this builder for fluent method chaining

withAcquireOnlyIfLockAlreadyExists

public AcquireLockOptions.AcquireLockOptionsBuilder withAcquireOnlyIfLockAlreadyExists(Boolean acquireOnlyIfLockAlreadyExists)

Sets whether or not to allow acquiring locks if the lock does not exist already

Parameters:

acquireOnlyIfLockAlreadyExists - If true, locks will not be granted on items which do not already exist. If false (default value), lock item will be created if it does not exist already.

Returns:

a reference to this builder for fluent method chaining

withRefreshPeriod

public AcquireLockOptions.AcquireLockOptionsBuilder withRefreshPeriod(Long refreshPeriod)

Parameters:

refreshPeriod - How long to wait before trying to get the lock again (if set to 10 seconds, for example, it would attempt to do so every 10 seconds). If set, TimeUnit must also be set.

Returns:

a reference to this builder for fluent method chaining

withAdditionalTimeToWaitForLock

public AcquireLockOptions.AcquireLockOptionsBuilder withAdditionalTimeToWaitForLock(Long additionalTimeToWaitForLock)

Parameters:

additionalTimeToWaitForLock - How long to wait in addition to the lease duration (if set to 10 minutes, this will try to acquire a lock for at least 10 minutes before giving up and throwing the exception). If set, TimeUnit must also be set.

Returns:

a reference to this builder for fluent method chaining

withTimeUnit

public AcquireLockOptions.AcquireLockOptionsBuilder withTimeUnit(TimeUnit timeUnit)

Parameters:

timeUnit - Sets the time unit for all time parameters set to non-null in this bean

Returns:

a reference to this builder for fluent method chaining

withAdditionalAttributes

public AcquireLockOptions.AcquireLockOptionsBuilder withAdditionalAttributes(Map<String,software.amazon.awssdk.services.dynamodb.model.AttributeValue> additionalAttributes)

Stores some additional attributes with each lock. This can be used to add any arbitrary parameters to each lock row.

Parameters:

additionalAttributes - an arbitrary map of attributes to store with the lock row to be acquired

Returns:

a reference to this builder for fluent method chaining

withUpdateExistingLockRecord

public AcquireLockOptions.AcquireLockOptionsBuilder withUpdateExistingLockRecord(Boolean updateExistingLockRecord)

With this being true lock client will only update the current lock record if present otherwise create a new one.

Parameters:

updateExistingLockRecord - whether lock client should always create a new lock record and removing any other entries not known to lock client

Returns:

a reference to this builder for fluent method chaining

withShouldSkipBlockingWait

public AcquireLockOptions.AcquireLockOptionsBuilder withShouldSkipBlockingWait(boolean shouldSkipBlockingWait)

With this being true, the lock client will not block the running thread and wait for lock, rather will fast fail the request, so that the caller can either choose to back-off and process the same request or start processing a new request.

Parameters:

shouldSkipBlockingWait - whether lock client should skip the logic to block the thread if lock is owned by another machine and lock is still active.

Returns:

a reference to this builder for fluent method chaining

withAcquireReleasedLocksConsistently

public AcquireLockOptions.AcquireLockOptionsBuilder withAcquireReleasedLocksConsistently(boolean acquireReleasedLocksConsistently)

With this being true, the lock client will ensure that released locks are acquired consistently in order to preserve existing lock data in dynamodb.

This option is currently disabled by default. Will be enabled by default in the next major release.

Parameters:

acquireReleasedLocksConsistently - whether the lock client should acquire released locks consistently

Returns:

a reference to this builder for fluent method chaining

withReentrant

public AcquireLockOptions.AcquireLockOptionsBuilder withReentrant(boolean reentrant)

With this set to true, the lock client will check first if it already owns the lock. If it already owns the lock and the lock is not expired, it will return the lock immediately. If this is set to false and the client already owns the lock, the call to acquireLock will block.

Parameters:

reentrant - whether the lock client should not block if it already owns the lock

Returns:

a reference to this builder for fluent method chaining

withSessionMonitor

public AcquireLockOptions.AcquireLockOptionsBuilder withSessionMonitor(long safeTimeWithoutHeartbeat,
                                                                       Optional<Runnable> sessionMonitorCallback)

Registers a "SessionMonitor."

The purpose of this SessionMonitor is to provide two abilities: provide the ability to determine if the lock is about to expire, and run a user-provided callback when the lock is about to expire. The advantage this provides is notification that your lock is about to expire before it is actually expired, and in case of leader election will help in preventing that there are no two leaders present simultaneously.

If due to any reason heartbeating is unsuccessful for a configurable period of time, your lock enters into a phase known as "danger zone." It is during this "danger zone" that the callback will be run. It is also during this period that a call to lockItem.amIAboutToExpire() will return true and your application can take appropriate measures.

Bear in mind that the callback on a SessionMonitor may be null. In this case, no callback will be run upon the lock entering the "danger zone"; yet, one can still make use of the amIAboutToExpire() method. Furthermore, non-null callbacks can only ever be executed once in a lock's lifetime. Independent of whether or not a callback is run, the client will attempt to heartbeat the lock until the lock is released or obtained by someone else.

Consider an example which uses this mechanism for leader election. One way to make use of this SessionMonitor is to register a callback that kills the JVM in case the leader's lock enters the danger zone:

 {
  final Runnable killJVM = new Runnable() {
      public void run() {
          Runtime.getRuntime().halt(1);
    }
  };
  try {
      final AcquireLockOptions options = AcquireLockOptions.builder("myLock")
          .withSessionMonitor(5L, killJVM)
          .withTimeUnit(TimeUnit.MINUTES)
          .build();
      final LockItem leaderLock = lockClient.acquireLock(options);
      goRunLeaderProcedures(); // safely run code knowing that after at least 5 minutes without heartbeating, the JVM will crash
  } catch (...) {
      ... //handle errors
  }
 }
 

Parameters:

safeTimeWithoutHeartbeat - the amount of time the lock can go without heartbeating before the lock is declared to be in the "danger zone"

sessionMonitorCallback - the callback to run when the lock's lease enters the danger zone

Returns:

a reference to this builder for fluent method chaining

build

public AcquireLockOptions build()

toString

public String toString()

Overrides:

toString in class Object