com.amazonaws.services.kinesis.leases.impl

Class LeaseManager<T extends Lease>

java.lang.Object

com.amazonaws.services.kinesis.leases.impl.LeaseManager<T>

All Implemented Interfaces:

ILeaseManager<T>

Direct Known Subclasses:

KinesisClientLeaseManager

public class LeaseManager<T extends Lease>
extends Object
implements ILeaseManager<T>

An implementation of ILeaseManager that uses DynamoDB.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	consistentReads
protected com.amazonaws.services.dynamodbv2.AmazonDynamoDB	dynamoDBClient
protected ILeaseSerializer<T>	serializer
protected String	table

Constructor Summary

Constructors

Constructor and Description
LeaseManager(String table, com.amazonaws.services.dynamodbv2.AmazonDynamoDB dynamoDBClient, ILeaseSerializer<T> serializer) Constructor.
LeaseManager(String table, com.amazonaws.services.dynamodbv2.AmazonDynamoDB dynamoDBClient, ILeaseSerializer<T> serializer, boolean consistentReads) Constructor for test cases - allows control of consistent reads.

Method Summary

Modifier and Type	Method and Description
protected DependencyException	convertAndRethrowExceptions(String operation, String leaseKey, com.amazonaws.AmazonClientException e)
boolean	createLeaseIfNotExists(T 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(T lease) Delete the given lease from DynamoDB.
boolean	evictLease(T lease) Evict the current owner of lease by setting owner to null.
T	getLease(String leaseKey)
boolean	leaseTableExists()
List<T>	listLeases() List all objects in table synchronously.
boolean	renewLease(T lease) Renew a lease by incrementing the lease counter.
boolean	takeLease(T lease, String owner) Take a lease for the given owner by incrementing its leaseCounter and setting its owner field.
boolean	updateLease(T 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.

Methods inherited from class java.lang.Object

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

Field Detail

table

protected String table

dynamoDBClient

protected com.amazonaws.services.dynamodbv2.AmazonDynamoDB dynamoDBClient

serializer

protected ILeaseSerializer<T extends Lease> serializer

consistentReads

protected boolean consistentReads

Constructor Detail

LeaseManager

public LeaseManager(String table,
                    com.amazonaws.services.dynamodbv2.AmazonDynamoDB dynamoDBClient,
                    ILeaseSerializer<T> serializer)

Constructor.

Parameters:

table - leases table

dynamoDBClient - DynamoDB client to use

serializer - LeaseSerializer to use to convert to/from DynamoDB objects.

LeaseManager

public LeaseManager(String table,
                    com.amazonaws.services.dynamodbv2.AmazonDynamoDB dynamoDBClient,
                    ILeaseSerializer<T> serializer,
                    boolean consistentReads)

Constructor for test cases - allows control of consistent reads. Consistent reads should only be used for testing - our code is meant to be resilient to inconsistent reads. Using consistent reads during testing speeds up execution of simple tests (you don't have to wait out the consistency window). Test cases that want to experience eventual consistency should not set consistentReads=true.

Parameters:

table - leases table

dynamoDBClient - DynamoDB client to use

serializer - lease serializer to use

consistentReads - true if we want consistent reads for testing purposes.

Method Detail

createLeaseTableIfNotExists

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

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

Specified by:

createLeaseTableIfNotExists in interface ILeaseManager<T extends Lease>

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

public boolean leaseTableExists()
                         throws DependencyException

Specified by:

leaseTableExists in interface ILeaseManager<T extends Lease>

Returns:

true if the lease table already exists.

Throws:

DependencyException - if DynamoDB describeTable fails in an unexpected way

waitUntilLeaseTableExists

public boolean waitUntilLeaseTableExists(long secondsBetweenPolls,
                                         long timeoutSeconds)
                                  throws DependencyException

Description copied from interface: ILeaseManager

Blocks until the lease table exists by polling leaseTableExists.

Specified by:

waitUntilLeaseTableExists in interface ILeaseManager<T extends Lease>

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

public List<T> listLeases()
                   throws DependencyException,
                          InvalidStateException,
                          ProvisionedThroughputException

List all objects in table synchronously.

Specified by:

listLeases in interface ILeaseManager<T extends Lease>

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

public boolean createLeaseIfNotExists(T lease)
                               throws DependencyException,
                                      InvalidStateException,
                                      ProvisionedThroughputException

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

Specified by:

createLeaseIfNotExists in interface ILeaseManager<T extends Lease>

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

public T getLease(String leaseKey)
           throws DependencyException,
                  InvalidStateException,
                  ProvisionedThroughputException

Specified by:

getLease in interface ILeaseManager<T extends Lease>

Parameters:

leaseKey - Get the lease for this shardId

Returns:

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

Throws:

DependencyException - if DynamoDB get fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB get fails due to lack of capacity

renewLease

public boolean renewLease(T 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.

Specified by:

renewLease in interface ILeaseManager<T extends Lease>

Parameters:

lease - the lease to renew

Returns:

true if renewal succeeded, false otherwise

Throws:

DependencyException - if DynamoDB update fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

takeLease

public boolean takeLease(T 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.

Specified by:

takeLease in interface ILeaseManager<T extends Lease>

Parameters:

lease - the lease to take

owner - the new owner

Returns:

true if lease was successfully taken, false otherwise

Throws:

DependencyException - if DynamoDB update fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

evictLease

public boolean evictLease(T 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.

Specified by:

evictLease in interface ILeaseManager<T extends Lease>

Parameters:

lease - the lease to void

Returns:

true if eviction succeeded, false otherwise

Throws:

DependencyException - if DynamoDB update fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

deleteAll

public void deleteAll()
               throws DependencyException,
                      InvalidStateException,
                      ProvisionedThroughputException

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

Specified by:

deleteAll in interface ILeaseManager<T extends Lease>

Throws:

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

InvalidStateException - if lease table does not exist

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

deleteLease

public void deleteLease(T lease)
                 throws DependencyException,
                        InvalidStateException,
                        ProvisionedThroughputException

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

Specified by:

deleteLease in interface ILeaseManager<T extends Lease>

Parameters:

lease - the lease to delete

Throws:

DependencyException - if DynamoDB delete fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB delete fails due to lack of capacity

updateLease

public boolean updateLease(T 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.

Specified by:

updateLease in interface ILeaseManager<T extends Lease>

Returns:

true if update succeeded, false otherwise

Throws:

DependencyException - if DynamoDB update fails in an unexpected way

InvalidStateException - if lease table does not exist

ProvisionedThroughputException - if DynamoDB update fails due to lack of capacity

convertAndRethrowExceptions

protected DependencyException convertAndRethrowExceptions(String operation,
                                                          String leaseKey,
                                                          com.amazonaws.AmazonClientException e)
                                                   throws ProvisionedThroughputException,
                                                          InvalidStateException

Throws:

ProvisionedThroughputException

InvalidStateException