software.amazon.kinesis.leases

Interface LeaseRenewer

All Known Implementing Classes:

DynamoDBLeaseRenewer

public interface LeaseRenewer

ILeaseRenewer objects are used by LeaseCoordinator to renew leases held by the LeaseCoordinator. Each LeaseCoordinator instance corresponds to one worker, and uses exactly one ILeaseRenewer to manage lease renewal for that worker.

Method Summary

Modifier and Type	Method and Description
void	addLeasesToRenew(Collection<Lease> newLeases) Adds leases to this LeaseRenewer's set of currently held leases.
void	clearCurrentlyHeldLeases() Clears this LeaseRenewer's set of currently held leases.
void	dropLease(Lease lease) Stops the lease renewer from continunig to maintain the given lease.
Lease	getCurrentlyHeldLease(String leaseKey)
Map<String,Lease>	getCurrentlyHeldLeases()
void	initialize() Bootstrap initial set of leases from the LeaseRefresher (e.g.
void	renewLeases() Attempt to renew all currently held leases.
boolean	updateLease(Lease lease, UUID concurrencyToken, String operation, String singleStreamShardId) Update application-specific fields in a currently held lease.

Method Detail

initialize

void initialize()
         throws DependencyException,
                InvalidStateException,
                ProvisionedThroughputException

Bootstrap initial set of leases from the LeaseRefresher (e.g. upon process restart, pick up leases we own)

Throws:

DependencyException - on unexpected DynamoDB failures

InvalidStateException - if lease table doesn't exist

ProvisionedThroughputException - if DynamoDB reads fail due to insufficient capacity

renewLeases

void renewLeases()
          throws DependencyException,
                 InvalidStateException

Attempt to renew all currently held leases.

Throws:

DependencyException - on unexpected DynamoDB failures

InvalidStateException - if lease table does not exist

getCurrentlyHeldLeases

Map<String,Lease> getCurrentlyHeldLeases()

Returns:

currently held leases. Key is shardId, value is corresponding Lease object. A lease is currently held if we successfully renewed it on the last run of renewLeases(). Lease objects returned are deep copies - their lease counters will not tick.

getCurrentlyHeldLease

Lease getCurrentlyHeldLease(String leaseKey)

Parameters:

leaseKey - key of the lease to retrieve

Returns:

a deep copy of a currently held lease, or null if we don't hold the lease

addLeasesToRenew

void addLeasesToRenew(Collection<Lease> newLeases)

Adds leases to this LeaseRenewer's set of currently held leases. Leases must have lastRenewalNanos set to the last time the lease counter was incremented before being passed to this method.

Parameters:

newLeases - new leases.

clearCurrentlyHeldLeases

void clearCurrentlyHeldLeases()

Clears this LeaseRenewer's set of currently held leases.

dropLease

void dropLease(Lease lease)

Stops the lease renewer from continunig to maintain the given lease.

Parameters:

lease - the lease to drop.

updateLease

boolean updateLease(Lease lease,
                    UUID concurrencyToken,
                    String operation,
                    String singleStreamShardId)
             throws DependencyException,
                    InvalidStateException,
                    ProvisionedThroughputException

Update application-specific fields in a currently held lease. Cannot be used to update internal fields such as leaseCounter, leaseOwner, etc. Fails if we do not hold the lease, or if the concurrency token does not match the concurrency token on the internal authoritative copy of the lease (ie, if we lost and re-acquired the lease).

Parameters:

lease - lease object containing updated data

concurrencyToken - obtained by calling Lease.concurrencyToken for a currently held lease

operation - that performs updateLease

singleStreamShardId - shardId for metrics emission in single stream mode. MultiStream mode will get the shardId from the lease object

Returns:

true if update succeeds, 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