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
boolean	createLeaseIfNotExists(Lease lease) Create a new lease.
boolean	createLeaseTableIfNotExists(Long readCapacity, Long writeCapacity) Creates the table that will store leases.
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 shardId) Gets the current checkpoint of the shard.
Lease	getLease(String shardId)
boolean	isLeaseTableEmpty() Check (synchronously) if there are any leases in the lease table.
boolean	leaseTableExists()
List<Lease>	listLeases() List all objects in table synchronously.
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.
boolean	waitUntilLeaseTableExists(long secondsBetweenPolls, long timeoutSeconds) Blocks until the lease table exists by polling leaseTableExists.

Method Detail

createLeaseTableIfNotExists

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

Creates the table that will store leases. Succeeds if table already exists.

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

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

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

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 shardId)
        throws DependencyException,
               InvalidStateException,
               ProvisionedThroughputException

Parameters:

shardId - Get the lease for this shardId

Returns:

lease for the specified shardId, 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

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

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 shardId)
                              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:

shardId - 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