com.bigdata.quorum

Interface Quorum<S extends Remote,C extends QuorumClient<S>>

All Known Implementing Classes:

AbstractQuorum, MockQuorumFixture.MockQuorum

public interface Quorum<S extends Remote,C extends QuorumClient<S>>

A quorum is a collection of services instances comprising the same logical service. The Quorum interface provides a view of the quorum from the perspective of one of those member services. A quorum has a replication factor k. A member service may "join" with a quorum when it shares an agreement with at least (k+1)/2 other quorum members concerning its state. When there are at least (k+1)/2 member services joined with the quorum, the quorum is "meets" and elects a leader. Each time a new leader is elected, it assigns a unique token to the quorum. Client reads and writes will block unless the quorum is met. If a quorum breaks, then any outstanding writes will be discarded and the client must wait until the quorum meets again before reading or writing on the quorum.

The first service in the chain is the quorum leader. Client writes are directed to the leader (also known as the master) and replicated to the member services joined with the quorum. Clients may read from any service in the quorum, but only for historical commit points. The current uncommitted state is only available from the quorum leader as the followers are only guaranteed to be consistent as of each commit point.

The services in the quorum are organized into a write pipeline for the purposes of replication. The leader is always the first service in the write pipeline. Services which are not yet joined with the quorum are allowed into the write pipeline while they are synchronizing with the leader. When a service is synchronized, it can then join the quorum.

This interface reflects state changes in the quorum for some logical service. Logical services and their physical instances are managed outside of the Quorum interface. When a physical service is starts or stops, it uses a Quorum for the corresponding logical service to observe and manage state changes in the emergent quorum of physical services for the same logical service.

Field Summary

Fields

Modifier and Type	Field and Description
static long	NO_QUORUM The constant used to indicate that there is no quorum (@value -1L).

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(QuorumListener listener) Add a listener
void	assertLeader(long token) Assert that the token is still valid and that the getClient() is the quorum leader.
void	assertQuorum(long token) Assert that the quorum associated with the token is still valid.
void	awaitBreak() Await a met break (blocking).
void	awaitBreak(long timeout, TimeUnit units) Await a met break (blocking).
long	awaitQuorum() Await a met quorum (blocking).
long	awaitQuorum(long timeout, TimeUnit units) Await a met quorum (blocking).
QuorumActor<S,C>	getActor() The object used to effect changes in distributed quorum state on the behalf of the QuorumMember.
Long	getCastVote(UUID serviceId) Return the vote cast by the service.
Long	getCastVoteIfConsensus(UUID serviceId) Search for the vote for the service.
C	getClient() Return the QuorumClient iff the quorum is running.
UUID[]	getJoined() Return the identifiers for the member services joined with this quorum.
UUID	getLastInPipeline() Return the UUID of the service which is the last service in the write pipeline.
UUID	getLeaderId() The UUID of the leader Quorum leader (non-blocking).
QuorumMember<S>	getMember() Return the QuorumMember iff the quorum is running.
UUID[]	getMembers() Return the identifiers for the member services (all known physical services for the logical service).
UUID[]	getPipeline() Return the service identifiers for the services in the write pipeline in the order in which they will accept and relay writes.
UUID[]	getPipelinePriorAndNext(UUID serviceId) Return the UUIDof the service in the pipeline which is immediately upstream from (prior to) and downstream from (next to) the specified service.
Map<Long,UUID[]>	getVotes() Return an immutable snapshot of the votes cast by the quorum members.
boolean	isHighlyAvailable() Return true if replicationFactor() is GT ONE (1).
boolean	isQuorum(int njoined) Return true iff the argument is large enough to constitute a quorum.
boolean	isQuorumFullyMet(long token) Return true iff the #of services joined with the quorum EQUALS k AND the provided quorum token is valid.
boolean	isQuorumMet() Return true iff the #of services joined with the quorum is GTE (k + 1)/2.
long	lastValidToken() The quorum token which was assigned the last time a leader was elected.
void	removeListener(QuorumListener listener) Remove a listener (the quorum's client is always a listener).
int	replicationFactor() Return k, the target replication factor.
void	start(C client) Start any asynchronous processing associated with maintaining the Quorum state.
void	terminate() Terminate any asynchronous processing associated with maintaining the Quorum state.
long	token() The current token for the quorum.

Field Detail

NO_QUORUM

static final long NO_QUORUM

The constant used to indicate that there is no quorum (@value -1L).

Note: The quorum token is formed by adding one to the lastValidToken(). The initial value of the lastValidToken() is -1L. Therefore, the the first valid quorum token is ZERO (0).

See Also:

Constant Field Values

Method Detail

replicationFactor

int replicationFactor()

Return k, the target replication factor.

A normal quorum requires a simple majority and a replication factor that is a non-negative odd integer (1, 3, 5, 7, etc). For this case, a quorum exists only when (k + 1)/2 physical services for the same logical service have an agreement on state. A single service with k := 1 is the degenerate case and has a minimum quorum size of ONE (1). High availability is only possible when k is GT ONE (1). Thus k := 3 is the minimum value for which services can be highly available and has a minimum quorum size of 2.

See Also:

isQuorum(int)

isQuorum

boolean isQuorum(int njoined)

Return true iff the argument is large enough to constitute a quorum.

Note: This method makes it easier to write code that obeys policies other than simple majority rule. For example, a quorum could exist only when ALL services are joined. This alternative rule is useful when the services do not support a resynchronization policy. For such services, all services must participate in all commits since services can not recover if they miss a commit. Simple replication is an example of this policy.

Parameters:

njoined - The argument.

Returns:

true if that a quorum is met for that many joined services.

token

long token()

The current token for the quorum. The initial value before the quorum has met is NO_QUORUM. When a leader is elected, it sets the current token as token := lastValidToken() + 1. The current token is cleared to NO_QUORUM if the leader leaves the met quorum. It is cleared NO_QUORUM if the quorum breaks. While a leader may be elected many times for the same lastCommitTime, a new quorum token is assigned each time a leader is elected.

lastValidToken

long lastValidToken()

The quorum token which was assigned the last time a leader was elected.

isHighlyAvailable

boolean isHighlyAvailable()

Return true if replicationFactor() is GT ONE (1). High availability exists (in principle) when the replicationFactor() k is greater than one. High availability exists (in practice) when the Quorum is met for a Quorum that is configured for high availability.

Returns:

true if this Quorum is highly available in principle

isQuorumMet

boolean isQuorumMet()

Return true iff the #of services joined with the quorum is GTE (k + 1)/2. A service with a met quorum is highly available in practice.

isQuorumFullyMet

boolean isQuorumFullyMet(long token)

Return true iff the #of services joined with the quorum EQUALS k AND the provided quorum token is valid. A service with a fully met quorum may be eligible to release storage associated with historical allocations since it does not need to maintain history in support of resynchronization of disconnected quorum services.

Parameters:

token - The quorum token.

Throws:

QuorumException - if the token is no longer valid.

addListener

void addListener(QuorumListener listener)

Add a listener

Parameters:

listener - The listener.

Throws:

IllegalArgumentException - if the listener is null.

IllegalArgumentException - if the listener is the quorum's client (the quorum's client is always a listener).

removeListener

void removeListener(QuorumListener listener)

Remove a listener (the quorum's client is always a listener).

Parameters:

listener - The listener.

Throws:

IllegalArgumentException - if the listener is null.

IllegalArgumentException - if the listener is the quorum's client (the quorum's client is always a listener).

getMembers

UUID[] getMembers()

Return the identifiers for the member services (all known physical services for the logical service).

Returns:

The UUIDs of the member services.

getVotes

Map<Long,UUID[]> getVotes()

Return an immutable snapshot of the votes cast by the quorum members.

getCastVote

Long getCastVote(UUID serviceId)

Return the vote cast by the service.

Parameters:

serviceId - The service.

Returns:

The vote cast by that service -or- null if the service has not cast a vote.

Throws:

IllegalArgumentException - if the serviceId is null.

getCastVoteIfConsensus

Long getCastVoteIfConsensus(UUID serviceId)

Search for the vote for the service.

Parameters:

serviceId - The service identifier.

Returns:

The lastCommitTime for which the service has cast its vote -or- null if the service is not participating in a consensus.

getJoined

UUID[] getJoined()

Return the identifiers for the member services joined with this quorum. If the quorum was met at the moment the request was processed, then the first element of the array was the quorum leader as of that moment and the remaining elements are followers (non-blocking).

Returns:

The UUIDs of the member services joined with this quorum.

getPipeline

UUID[] getPipeline()

Return the service identifiers for the services in the write pipeline in the order in which they will accept and relay writes.

Returns:

The UUIDs of the ordered services in the write pipeline.

getLastInPipeline

UUID getLastInPipeline()

Return the UUID of the service which is the last service in the write pipeline.

Returns:

The UUID of the last service in the write pipeline or null if there are no services in the write pipeline.

getPipelinePriorAndNext

UUID[] getPipelinePriorAndNext(UUID serviceId)

Return the UUIDof the service in the pipeline which is immediately upstream from (prior to) and downstream from (next to) the specified service. These are, respectively, the service from which it receives data (upstream) and to which it sends data (downstream).

Parameters:

serviceId - The service id.

Returns:

Either null if the serviceId does not appear in the write pipeline -or- an array of two elements whose values are: [0] The upstream serviceId in the write pipeline, which will be null iff serviceId is the first service in the write pipeline; and [1] The downstream service in the write pipeline, which will be null iff serviceId is the last service in the write pipeline.

awaitQuorum

long awaitQuorum()
                 throws InterruptedException,
                        AsynchronousQuorumCloseException

Await a met quorum (blocking). If the Quorumis not met, then this will block until the Quorum meets.

Returns:

The current quorum token.

Throws:

AsynchronousQuorumCloseException - if terminate() is invoked while awaiting a quorum meet.

InterruptedException

awaitQuorum

long awaitQuorum(long timeout,
               TimeUnit units)
                 throws InterruptedException,
                        AsynchronousQuorumCloseException,
                        TimeoutException

Await a met quorum (blocking). If the Quorumis not met, then this will block until the Quorum meets.

Parameters:

timeout - The timeout.

units - The timeout units.

Returns:

The current quorum token.

Throws:

AsynchronousQuorumCloseException - if terminate() is invoked while awaiting a quorum meet.

TimeoutException - if the timeout expired before the quorum met.

InterruptedException

awaitBreak

void awaitBreak()
                throws InterruptedException,
                       AsynchronousQuorumCloseException

Await a met break (blocking). If the Quorum is met, then this will block until the Quorum breaks.

Throws:

AsynchronousQuorumCloseException - if terminate() is invoked while awaiting a quorum break.

InterruptedException

awaitBreak

void awaitBreak(long timeout,
              TimeUnit units)
                throws InterruptedException,
                       AsynchronousQuorumCloseException,
                       TimeoutException

Await a met break (blocking). If the Quorum is met, then this will block until the Quorum breaks.

Parameters:

timeout - The timeout.

units - The timeout units.

Throws:

AsynchronousQuorumCloseException - if terminate() is invoked while awaiting a quorum break.

TimeoutException - if the timeout expired before the quorum breaks.

InterruptedException

assertQuorum

void assertQuorum(long token)

Assert that the quorum associated with the token is still valid. The pattern for using this method is to save the token() somewhere. This method may then be invoked to verify that the saved token is still valid and, hence, that the quorum is still met.

Parameters:

token - The token for the quorum.

Throws:

QuorumException - if the quorum is not met.

QuorumException - if the quorum is not met on a the caller's token.

QuorumException - if the token is NO_QUORUM.

assertLeader

void assertLeader(long token)

Assert that the token is still valid and that the getClient() is the quorum leader.

Parameters:

token - A quorum token.

Throws:

QuorumException - if the quorum is invalid.

QuorumException - if the token is NO_QUORUM.

QuorumException - if our client is not the quorum leader.

getLeaderId

UUID getLeaderId()

The UUID of the leader Quorum leader (non-blocking).

Returns:

The UUID of the leader Quorum leader -or- null if the quorum is not met.

start

void start(C client)

Start any asynchronous processing associated with maintaining the Quorum state.

terminate

void terminate()

Terminate any asynchronous processing associated with maintaining the Quorum state.

getClient

C getClient()

Return the QuorumClient iff the quorum is running.

Returns:

The QuorumClient.

Throws:

IllegalStateException - if the quorum is not running.

getMember

QuorumMember<S> getMember()

Return the QuorumMember iff the quorum is running.

Returns:

The QuorumMember.

Throws:

IllegalStateException - if the quorum is not running.

UnsupportedOperationException - if the client does not implement QuorumMember.

getActor

QuorumActor<S,C> getActor()

The object used to effect changes in distributed quorum state on the behalf of the QuorumMember.

Returns:

The QuorumActor which will effect changes in the distributed state of the quorum.

Throws:

IllegalStateException - if the quorum is not running.

IllegalStateException - if the client is not a QuorumMember.