public static class AcquireLockOptions.AcquireLockOptionsBuilder
extends java.lang.Object
public AcquireLockOptions.AcquireLockOptionsBuilder withSortKey(java.lang.String sortKey)
sortKey - The sort key to try and acquire the lock on (specify if
and only if the table has sort keys.)public AcquireLockOptions.AcquireLockOptionsBuilder withData(java.nio.ByteBuffer data)
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)public AcquireLockOptions.AcquireLockOptionsBuilder withReplaceData(java.lang.Boolean replaceData)
replaceData - If true, this will replace the lock data currently stored
alongside the lock.public AcquireLockOptions.AcquireLockOptionsBuilder withDeleteLockOnRelease(java.lang.Boolean deleteLockOnRelease)
deleteLockOnRelease - Whether or not the lock should be deleted when close() is
called on the resulting LockItempublic AcquireLockOptions.AcquireLockOptionsBuilder withRefreshPeriod(java.lang.Long refreshPeriod)
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.public AcquireLockOptions.AcquireLockOptionsBuilder withAdditionalTimeToWaitForLock(java.lang.Long additionalTimeToWaitForLock)
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.public AcquireLockOptions.AcquireLockOptionsBuilder withTimeUnit(java.util.concurrent.TimeUnit timeUnit)
timeUnit - Sets the time unit for all time parameters set to non-null
in this beanpublic AcquireLockOptions.AcquireLockOptionsBuilder withAdditionalAttributes(java.util.Map<java.lang.String,AttributeValue> additionalAttributes)
additionalAttributes - an arbitrary map of attributes to store with the lock row to be acquiredpublic AcquireLockOptions.AcquireLockOptionsBuilder withSessionMonitor(long safeTimeWithoutHeartbeat, java.util.Optional<java.lang.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
}
}
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
zonepublic AcquireLockOptions.AcquireLockOptionsBuilder withRequestMetricCollector(RequestMetricCollector requestMetricCollector)
requestMetricCollector - The request level metric collector to use; takes precedence over the ones at the
http client level and AWS SDK level.public AcquireLockOptions build()
public java.lang.String toString()
toString in class java.lang.Object