Package com.amazonaws.services.dynamodbv2

Class 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 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. This only skips the blocking wait for a lock that is currently held by another owner. Other retryable failures, such as DynamoDB client exceptions or acquiring only if a missing lock already exists, may still follow the normal acquire retry behavior. A caller that repeatedly retries with the same AmazonDynamoDBLockClient instance can still acquire an otherwise stale lock once it observes the same record version number for longer than the lock lease duration. This stale-lock observation is kept in a bounded in-memory cache on the lock client. If that observation is evicted, the client must observe the same record version number again before it can acquire the stale lock with skip blocking wait enabled.
        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