software.amazon.kinesis.leases

Interface LeaseRefresher

All Known Implementing Classes:

DynamoDBLeaseRefresher

public interface LeaseRefresher

Supports basic CRUD operations for Leases.

Method Summary

Modifier and Type	Method and Description
default boolean	assignLease(Lease lease, String newOwner) Assigns given lease to newOwner owner by incrementing its leaseCounter and setting its owner field.
boolean	createLeaseIfNotExists(Lease lease) Create a new lease.
default String	createLeaseOwnerToLeaseKeyIndexIfNotExists() Creates the LeaseOwnerToLeaseKey index on the lease table if it doesn't exist and returns the status of index.
boolean	createLeaseTableIfNotExists() Creates the table that will store leases.
boolean	createLeaseTableIfNotExists(Long readCapacity, Long writeCapacity) Deprecated.
void	deleteAll() Delete all leases from DynamoDB.
void	deleteLease(Lease lease) Delete the given lease from DynamoDB.
boolean	evictLease(Lease lease) Evict the current owner of lease by setting owner to null.
ExtendedSequenceNumber	getCheckpoint(String leaseKey) Gets the current checkpoint of the shard.
Lease	getLease(String leaseKey)
default boolean	initiateGracefulLeaseHandoff(Lease lease, String newOwner) Initiates a graceful handoff of the given lease to the specified new owner, allowing the current owner to complete its processing before transferring ownership.
boolean	isLeaseOwnerToLeaseKeyIndexActive() Check if leaseOwner GSI is ACTIVE
boolean	isLeaseTableEmpty() Check (synchronously) if there are any leases in the lease table.
boolean	leaseTableExists()
default List<String>	listLeaseKeysForWorker(String workerIdentifier) List all leases for a given workerIdentifier synchronously.
List<Lease>	listLeases() List all objects in table synchronously.
List<Lease>	listLeasesForStream(StreamIdentifier streamIdentifier) List all leases for a given stream synchronously.
default Map.Entry<List<Lease>,List<String>>	listLeasesParallely(ExecutorService threadPool, int parallelismFactor) List all leases from the storage parallely and deserialize into Lease objects.
boolean	renewLease(Lease lease) Renew a lease by incrementing the lease counter.
boolean	takeLease(Lease lease, String owner) Take a lease for the given owner by incrementing its leaseCounter and setting its owner field.
boolean	updateLease(Lease lease) Update application-specific fields of the given lease in DynamoDB.
default void	updateLeaseWithMetaInfo(Lease lease, UpdateField updateField) Update application-specific fields of the given lease in DynamoDB.
default boolean	waitUntilLeaseOwnerToLeaseKeyIndexExists(long secondsBetweenPolls, long timeoutSeconds) Blocks until the index exists by polling storage till either the index is ACTIVE or else timeout has happened.
boolean	waitUntilLeaseTableExists(long secondsBetweenPolls, long timeoutSeconds) Blocks until the lease table exists by polling leaseTableExists.

Method Detail

createLeaseTableIfNotExists

@Deprecated
boolean createLeaseTableIfNotExists(Long readCapacity,
                                                Long writeCapacity)
                                         throws ProvisionedThroughputException,
                                                DependencyException

Deprecated.

Creates the table that will store leases. Succeeds if table already exists. Deprecated. Use createLeaseTableIfNotExists().

Parameters:

readCapacity -

writeCapacity -

Returns:

true if we created a new table (table didn't exist before)

Throws:

ProvisionedThroughputException - if we cannot create the lease table due to per-AWS-account capacity restrictions.

DependencyException - if DynamoDB createTable fails in an unexpected way

createLeaseTableIfNotExists

boolean createLeaseTableIfNotExists()
                             throws ProvisionedThroughputException,
                                    DependencyException

Creates the table that will store leases. Table is now created in PayPerRequest billing mode by default. Succeeds if table already exists.

Returns:

true if we created a new table (table didn't exist before)

Throws:

ProvisionedThroughputException - if we cannot create the lease table due to per-AWS-account capacity restrictions.

DependencyException - if DynamoDB createTable fails in an unexpected way

leaseTableExists

boolean leaseTableExists()
                  throws DependencyException

Returns:

true if the lease table already exists.

Throws:

DependencyException - if DynamoDB describeTable fails in an unexpected way

waitUntilLeaseTableExists

boolean waitUntilLeaseTableExists(long secondsBetweenPolls,
                                  long timeoutSeconds)
                           throws DependencyException

Blocks until the lease table exists by polling leaseTableExists.

Parameters:

secondsBetweenPolls - time to wait between polls in seconds

timeoutSeconds - total time to wait in seconds

Returns:

true if table exists, false if timeout was reached

Throws:

DependencyException - if DynamoDB describeTable fails in an unexpected way

createLeaseOwnerToLeaseKeyIndexIfNotExists

default String createLeaseOwnerToLeaseKeyIndexIfNotExists()
                                                   throws DependencyException

Creates the LeaseOwnerToLeaseKey index on the lease table if it doesn't exist and returns the status of index.

Returns:

indexStatus status of the index.

Throws:

DependencyException - if storage's describe API fails in an unexpected way

waitUntilLeaseOwnerToLeaseKeyIndexExists

default boolean waitUntilLeaseOwnerToLeaseKeyIndexExists(long secondsBetweenPolls,
                                                         long timeoutSeconds)

Blocks until the index exists by polling storage till either the index is ACTIVE or else timeout has happened.

Parameters:

secondsBetweenPolls - time to wait between polls in seconds

timeoutSeconds - total time to wait in seconds

Returns:

true if index on the table exists and is ACTIVE, false if timeout was reached

isLeaseOwnerToLeaseKeyIndexActive

boolean isLeaseOwnerToLeaseKeyIndexActive()
                                   throws DependencyException

Check if leaseOwner GSI is ACTIVE

Returns:

true if index is active, false otherwise

Throws:

DependencyException - if storage's describe API fails in an unexpected way

listLeasesForStream

List<Lease> listLeasesForStream(StreamIdentifier streamIdentifier)
                         throws DependencyException,
                                InvalidStateException,
                                ProvisionedThroughputException

List all leases for a given stream synchronously.

Returns:

list of leases

Throws:

DependencyException - if DynamoDB scan fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB scan fails due to lack of capacity

listLeaseKeysForWorker

default List<String> listLeaseKeysForWorker(String workerIdentifier)
                                     throws DependencyException,
                                            InvalidStateException,
                                            ProvisionedThroughputException

List all leases for a given workerIdentifier synchronously. Default implementation calls listLeases() and filters the results.

Returns:

list of leases

Throws:

DependencyException - if DynamoDB scan fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB scan fails due to lack of capacity

listLeases

List<Lease> listLeases()
                throws DependencyException,
                       InvalidStateException,
                       ProvisionedThroughputException

List all objects in table synchronously.

Returns:

list of leases

Throws:

DependencyException - if DynamoDB scan fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB scan fails due to lack of capacity

listLeasesParallely

default Map.Entry<List<Lease>,List<String>> listLeasesParallely(ExecutorService threadPool,
                                                                int parallelismFactor)
                                                         throws DependencyException,
                                                                InvalidStateException,
                                                                ProvisionedThroughputException

List all leases from the storage parallely and deserialize into Lease objects. Returns the list of leaseKey that failed deserialize separately.

Parameters:

threadPool - threadpool to use for parallel scan

parallelismFactor - no. of parallel scans

Returns:

Pair of List of leases from the storage and List of items failed to deserialize

Throws:

DependencyException - if DynamoDB scan fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB scan fails due to lack of capacity

createLeaseIfNotExists

boolean createLeaseIfNotExists(Lease lease)
                        throws DependencyException,
                               InvalidStateException,
                               ProvisionedThroughputException

Create a new lease. Conditional on a lease not already existing with this shardId.

Parameters:

lease - the lease to create

Returns:

true if lease was created, false if lease already exists

Throws:

DependencyException - if DynamoDB put fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB put fails due to lack of capacity

getLease

Lease getLease(String leaseKey)
        throws DependencyException,
               InvalidStateException,
               ProvisionedThroughputException

Parameters:

leaseKey - Get the lease for this leasekey

Returns:

lease for the specified leaseKey, or null if one doesn't exist

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB get fails due to lack of capacity

DependencyException - if DynamoDB get fails in an unexpected way

renewLease

boolean renewLease(Lease lease)
            throws DependencyException,
                   InvalidStateException,
                   ProvisionedThroughputException

Renew a lease by incrementing the lease counter. Conditional on the leaseCounter in DynamoDB matching the leaseCounter of the input. Mutates the leaseCounter of the passed-in lease object after updating the record in DynamoDB.

Parameters:

lease - the lease to renew

Returns:

true if renewal succeeded, false otherwise

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

DependencyException - if DynamoDB update fails in an unexpected way

takeLease

boolean takeLease(Lease lease,
                  String owner)
           throws DependencyException,
                  InvalidStateException,
                  ProvisionedThroughputException

Take a lease for the given owner by incrementing its leaseCounter and setting its owner field. Conditional on the leaseCounter in DynamoDB matching the leaseCounter of the input. Mutates the leaseCounter and owner of the passed-in lease object after updating DynamoDB.

Parameters:

lease - the lease to take

owner - the new owner

Returns:

true if lease was successfully taken, false otherwise

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

DependencyException - if DynamoDB update fails in an unexpected way

assignLease

default boolean assignLease(Lease lease,
                            String newOwner)
                     throws DependencyException,
                            InvalidStateException,
                            ProvisionedThroughputException

Assigns given lease to newOwner owner by incrementing its leaseCounter and setting its owner field. Conditional on the leaseOwner in DynamoDB matching the leaseOwner of the input lease. Mutates the leaseCounter and owner of the passed-in lease object after updating DynamoDB.

Parameters:

lease - the lease to be assigned

newOwner - the new owner

Returns:

true if lease was successfully assigned, false otherwise

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

DependencyException - if DynamoDB update fails in an unexpected way

initiateGracefulLeaseHandoff

default boolean initiateGracefulLeaseHandoff(Lease lease,
                                             String newOwner)
                                      throws DependencyException,
                                             InvalidStateException,
                                             ProvisionedThroughputException

Initiates a graceful handoff of the given lease to the specified new owner, allowing the current owner to complete its processing before transferring ownership.

This method updates the lease with the new owner information but ensures that the current owner is given time to gracefully finish its work (e.g., processing records) before the lease is reassigned.

Parameters:

lease - the lease to be assigned

newOwner - the new owner

Returns:

true if a graceful handoff was successfully initiated

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

DependencyException - if DynamoDB update fails in an unexpected way

evictLease

boolean evictLease(Lease lease)
            throws DependencyException,
                   InvalidStateException,
                   ProvisionedThroughputException

Evict the current owner of lease by setting owner to null. Conditional on the owner in DynamoDB matching the owner of the input. Mutates the lease counter and owner of the passed-in lease object after updating the record in DynamoDB.

Parameters:

lease - the lease to void

Returns:

true if eviction succeeded, false otherwise

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

DependencyException - if DynamoDB update fails in an unexpected way

deleteLease

void deleteLease(Lease lease)
          throws DependencyException,
                 InvalidStateException,
                 ProvisionedThroughputException

Delete the given lease from DynamoDB. Does nothing when passed a lease that does not exist in DynamoDB.

Parameters:

lease - the lease to delete

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB delete fails due to lack of capacity

DependencyException - if DynamoDB delete fails in an unexpected way

deleteAll

void deleteAll()
        throws DependencyException,
               InvalidStateException,
               ProvisionedThroughputException

Delete all leases from DynamoDB. Useful for tools/utils and testing.

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB scan or delete fail due to lack of capacity

DependencyException - if DynamoDB scan or delete fail in an unexpected way

updateLease

boolean updateLease(Lease lease)
             throws DependencyException,
                    InvalidStateException,
                    ProvisionedThroughputException

Update application-specific fields of the given lease in DynamoDB. Does not update fields managed by the leasing library such as leaseCounter, leaseOwner, or leaseKey. Conditional on the leaseCounter in DynamoDB matching the leaseCounter of the input. Increments the lease counter in DynamoDB so that updates can be contingent on other updates. Mutates the lease counter of the passed-in lease object.

Returns:

true if update succeeded, false otherwise

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

DependencyException - if DynamoDB update fails in an unexpected way

updateLeaseWithMetaInfo

default void updateLeaseWithMetaInfo(Lease lease,
                                     UpdateField updateField)
                              throws DependencyException,
                                     InvalidStateException,
                                     ProvisionedThroughputException

Update application-specific fields of the given lease in DynamoDB. Does not update fields managed by the leasing library such as leaseCounter, leaseOwner, or leaseKey.

Throws:

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

DependencyException - if DynamoDB update fails in an unexpected way

isLeaseTableEmpty

boolean isLeaseTableEmpty()
                   throws DependencyException,
                          InvalidStateException,
                          ProvisionedThroughputException

Check (synchronously) if there are any leases in the lease table.

Returns:

true if there are no leases in the lease table

Throws:

DependencyException - if DynamoDB scan fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB scan fails due to lack of capacity

getCheckpoint

ExtendedSequenceNumber getCheckpoint(String leaseKey)
                              throws ProvisionedThroughputException,
                                     InvalidStateException,
                                     DependencyException

Gets the current checkpoint of the shard. This is useful in the resharding use case where we will wait for the parent shard to complete before starting on the records from a child shard.

Parameters:

leaseKey - Checkpoint of this shard will be returned

Returns:

Checkpoint of this shard, or null if the shard record doesn't exist.

Throws:

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

InvalidStateException - if lease table does not exist

DependencyException - if DynamoDB update fails in an unexpected way