com.bigdata.quorum

Class AbstractQuorumMember<S extends Remote>

java.lang.Object

com.bigdata.quorum.AbstractQuorumClient<S>

com.bigdata.quorum.AbstractQuorumMember<S>

All Implemented Interfaces:

QuorumClient<S>, QuorumListener, QuorumMember<S>, QuorumStateChangeListener, ServiceLookup<S>

Direct Known Subclasses:

QuorumServiceBase

public abstract class AbstractQuorumMember<S extends Remote>
extends AbstractQuorumClient<S>
implements QuorumMember<S>

Abstract base class for a QuorumMember.

Version:

$Id$

Author:

Bryan Thompson

Field Summary

Fields inherited from class com.bigdata.quorum.AbstractQuorumClient

log

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractQuorumMember(String logicalServiceId, UUID serviceId)

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addListener(QuorumStateChangeListener listener) Add a delegate listener.
protected void	assertFollower(long token)
void	assertLeader(long token) Assert that this is the quorum leader.
protected void	assertQuorum(long token)
void	consensus(long lastCommitTime) Invoked when a consensus has been achieved among (k+1)/2 services concerning a shared lastCommitTime (really, this is not a consensus but a simple majority).
QuorumActor<S,QuorumMember<S>>	getActor() Return the actor for this QuorumMember (it is allocated by AbstractQuorum.start(QuorumClient)).
UUID	getDownstreamServiceId() Return the UUID of the service (if any) downstream from this service in the write pipeline.
S	getLeader(long token) Return the remote interface used to perform HA operations on the quorum leader.
abstract S	getService(UUID serviceId) Return the remote interface used to perform HA operations on a member of quorum.
UUID	getServiceId() The identifier for this service (the quorum member).
boolean	isFollower(long token) Return true iff this node is a quorum follower.
boolean	isJoinedMember(long token) Return true if the service is joined with the quorum.
boolean	isLastInChain(long token) Return true iff the quorum is highly available and this node is last one in the write pipeline (it will not return true for a singleton quorum where the only node is the master).
boolean	isLeader(long token) Return true iff this node is the quorum leader.
boolean	isMember() Return trueif the quorum recognizes the service as a member of that quorum.
boolean	isPipelineMember() Return true if quorum recognizes the service is part of the write pipeline.
void	lostConsensus() Invoked when the consensus is lost.
void	memberAdd() Invoked when this service is added as a quorum member.
void	memberRemove() Invoked when this service is removed as a quorum member.
void	pipelineAdd() Invoked when this service is added to the write pipeline.
void	pipelineChange(UUID oldDownStreamId, UUID newDownStreamId) Invoked for this service when the downstream service in the write pipeline has changed.
void	pipelineElectedLeader() Invoked for this service when the service is already in the pipeline and this service becomes the first service in the write pipeline because all previous services in the pipeline order have been removed from the pipeline (failover into the leader position).
void	pipelineRemove() Invoked when this service is removed from the write pipeline.
void	pipelineUpstreamChange() Invoked for this service when the upstream service in the write pipeline has been removed.
void	quorumBreak() Invoked when a quorum breaks.
void	quorumMeet(long token, UUID leaderId) Invoked when a quorum meets.
protected void	removeListener(QuorumStateChangeListener listener) Remove a delegate listener.
void	serviceJoin() Invoked when this service joins the quorum.
void	serviceLeave() Invoked when this service leaves the quorum.

Methods inherited from class com.bigdata.quorum.AbstractQuorumClient

disconnected, getLogicalServiceZPath, getQuorum, notify, start, terminate

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.bigdata.quorum.QuorumMember

getExecutor, getService

Methods inherited from interface com.bigdata.quorum.QuorumClient

disconnected, getLogicalServiceZPath, getQuorum, start, terminate

Methods inherited from interface com.bigdata.quorum.QuorumListener

notify

Constructor Detail

AbstractQuorumMember

protected AbstractQuorumMember(String logicalServiceId,
                    UUID serviceId)

Method Detail

getLeader

public S getLeader(long token)

Description copied from interface: QuorumClient

Return the remote interface used to perform HA operations on the quorum leader.

Specified by:

getLeader in interface QuorumClient<S extends Remote>

Overrides:

getLeader in class AbstractQuorumClient<S extends Remote>

Parameters:

token - The quorum token for which the request was made.

Returns:

The remote interface for the leader.

getService

public abstract S getService(UUID serviceId)

Description copied from interface: QuorumClient

Return the remote interface used to perform HA operations on a member of quorum.

Specified by:

getService in interface QuorumClient<S extends Remote>

Specified by:

getService in interface ServiceLookup<S extends Remote>

Specified by:

getService in class AbstractQuorumClient<S extends Remote>

Parameters:

serviceId - The UUID associated with the service.

Returns:

The remote interface for that quorum member.

getServiceId

public UUID getServiceId()

Description copied from interface: QuorumMember

The identifier for this service (the quorum member). Each quorum member is a physical service instance of some highly available logical service.

Specified by:

getServiceId in interface QuorumMember<S extends Remote>

See Also:

QuorumClient.getLogicalServiceZPath()

getActor

public QuorumActor<S,QuorumMember<S>> getActor()

Return the actor for this QuorumMember (it is allocated by AbstractQuorum.start(QuorumClient)).

Specified by:

getActor in interface QuorumMember<S extends Remote>

isMember

public boolean isMember()

Description copied from interface: QuorumMember

Return trueif the quorum recognizes the service as a member of that quorum. The quorum token is not required for this method because membership status does not change with a quorum meet or break.

Specified by:

isMember in interface QuorumMember<S extends Remote>

isPipelineMember

public boolean isPipelineMember()

Description copied from interface: QuorumMember

Return true if quorum recognizes the service is part of the write pipeline. The quorum token is not required for this method because pipeline status does not change with a quorum meet or break. Once a service is receiving synchronous messages from a Quorum it will notice when it enters and leaves the pipeline and when the downstream service for this service changes in the quorum.

Specified by:

isPipelineMember in interface QuorumMember<S extends Remote>

isJoinedMember

public boolean isJoinedMember(long token)

Description copied from interface: QuorumMember

Return true if the service is joined with the quorum.

Note: This method DOES NOT throw an exception if the quorum is not met, but it will not return true unless the quorum is met.

Specified by:

isJoinedMember in interface QuorumMember<S extends Remote>

Parameters:

token - The quorum token for which the request was made.

isLeader

public boolean isLeader(long token)

Description copied from interface: QuorumMember

Return true iff this node is the quorum leader. The quorum leader is the only node which will accept writes. Note that is always true when the #replicationFactor() is ONE (1).

Specified by:

isLeader in interface QuorumMember<S extends Remote>

Parameters:

token - The quorum token for which the request was made.

isFollower

public boolean isFollower(long token)

Description copied from interface: QuorumMember

Return true iff this node is a quorum follower. This is true of all nodes in a Q except for the leader.

Specified by:

isFollower in interface QuorumMember<S extends Remote>

Parameters:

token - The quorum token for which the request was made.

isLastInChain

public boolean isLastInChain(long token)

Description copied from interface: QuorumMember

Return true iff the quorum is highly available and this node is last one in the write pipeline (it will not return true for a singleton quorum where the only node is the master).

Specified by:

isLastInChain in interface QuorumMember<S extends Remote>

Parameters:

token - The quorum token for which the request was made.

getDownstreamServiceId

public UUID getDownstreamServiceId()

Description copied from interface: QuorumMember

Return the UUID of the service (if any) downstream from this service in the write pipeline.

Specified by:

getDownstreamServiceId in interface QuorumMember<S extends Remote>

Returns:

The UUID of the downstream service in the write pipeline. This will return null for services which are not part of the write pipeline, for the leader, and for the last service in the write pipeline.

assertQuorum

protected void assertQuorum(long token)

assertLeader

public void assertLeader(long token)

Description copied from interface: QuorumMember

Assert that this is the quorum leader.

Specified by:

assertLeader in interface QuorumMember<S extends Remote>

Parameters:

token - The quorum token for which the request was made.

assertFollower

protected void assertFollower(long token)

addListener

protected void addListener(QuorumStateChangeListener listener)

Add a delegate listener.

Parameters:

listener - The listener.

removeListener

protected void removeListener(QuorumStateChangeListener listener)

Remove a delegate listener.

Parameters:

listener - The listener.

memberAdd

public void memberAdd()

Description copied from interface: QuorumStateChangeListener

Invoked when this service is added as a quorum member.

Specified by:

memberAdd in interface QuorumStateChangeListener

memberRemove

public void memberRemove()

Description copied from interface: QuorumStateChangeListener

Invoked when this service is removed as a quorum member.

Specified by:

memberRemove in interface QuorumStateChangeListener

pipelineAdd

public void pipelineAdd()

Description copied from interface: QuorumStateChangeListener

Invoked when this service is added to the write pipeline. The service always enters at the of the pipeline.

Specified by:

pipelineAdd in interface QuorumStateChangeListener

pipelineRemove

public void pipelineRemove()

Description copied from interface: QuorumStateChangeListener

Invoked when this service is removed from the write pipeline.

Specified by:

pipelineRemove in interface QuorumStateChangeListener

pipelineElectedLeader

public void pipelineElectedLeader()

Description copied from interface: QuorumStateChangeListener

Invoked for this service when the service is already in the pipeline and this service becomes the first service in the write pipeline because all previous services in the pipeline order have been removed from the pipeline (failover into the leader position).

Specified by:

pipelineElectedLeader in interface QuorumStateChangeListener

pipelineChange

public void pipelineChange(UUID oldDownStreamId,
                  UUID newDownStreamId)

Description copied from interface: QuorumStateChangeListener

Invoked for this service when the downstream service in the write pipeline has changed. Services always enter at the end of the write pipeline, but may be removed at any position in the write pipeline.

Specified by:

pipelineChange in interface QuorumStateChangeListener

pipelineUpstreamChange

public void pipelineUpstreamChange()

Description copied from interface: QuorumStateChangeListener

Invoked for this service when the upstream service in the write pipeline has been removed. This hook provides an opportunity for this service to close out its connection with the old upstream service and to prepare to establish a new connection with the new downstream service.

Specified by:

pipelineUpstreamChange in interface QuorumStateChangeListener

consensus

public void consensus(long lastCommitTime)

Description copied from interface: QuorumStateChangeListener

Invoked when a consensus has been achieved among (k+1)/2 services concerning a shared lastCommitTime (really, this is not a consensus but a simple majority). This message is sent to each member service regardless of whether or not they participated in the consensus.

Once a consensus has been reached, each QuorumMember which agrees on that lastCommitTime MUST do a QuorumStateChangeListener.serviceJoin() before the quorum will meet. The first quorum member to do a service join will be elected the leader. The remaining services to do a service join will be elected followers.

Specified by:

consensus in interface QuorumStateChangeListener

Parameters:

lastCommitTime - The last commit time around which a consensus was established.

See Also:

QuorumStateChangeListener.serviceJoin(), #electedLeader(long), #electedFollower(long), QuorumStateChangeListener.lostConsensus()

lostConsensus

public void lostConsensus()

Description copied from interface: QuorumStateChangeListener

Invoked when the consensus is lost. Services do not withdraw their cast votes until a quorum breaks and a new consensus needs to be established. This message is sent to each member service regardless of whether or not they participated in the consensus.

Specified by:

lostConsensus in interface QuorumStateChangeListener

See Also:

QuorumStateChangeListener.consensus(long)

serviceJoin

public void serviceJoin()

Description copied from interface: QuorumStateChangeListener

Invoked when this service joins the quorum.

Specified by:

serviceJoin in interface QuorumStateChangeListener

serviceLeave

public void serviceLeave()

Description copied from interface: QuorumStateChangeListener

Invoked when this service leaves the quorum.

Specified by:

serviceLeave in interface QuorumStateChangeListener

quorumBreak

public void quorumBreak()

Description copied from interface: QuorumStateChangeListener

Invoked when a quorum breaks. The service MUST handle handle this event by (a) doing an abort() which will any buffered writes and reload their current root block; and (b) casting a vote for their current commit time. Once a consensus is reached on the current commit time, services will be joined in the vote order, a new leader will be elected, and the quorum will meet again. This message is sent to all member services, regardless of whether they were joined with the met quorum.

Specified by:

quorumBreak in interface QuorumStateChangeListener

quorumMeet

public void quorumMeet(long token,
              UUID leaderId)

Description copied from interface: QuorumStateChangeListener

Invoked when a quorum meets. The state of the met quorum can be queried using the token. Quorum members can use this to decide whether they are the leader (using #isLeader(long), joined as a follower (using #isFollower(long)), or do not participate in the quorum (this message is sent to all quorum members, so this service might not be part of the met qourum).

The following pre-conditions will be satisfied before this message is sent to the QuorumMember:

• There will be at least (k+1)/2 services which have voted for the same lastCommitTime.
• There will be at (k+1)/2 services joined with the quorum. The join order will be the same as the Quorum.getVotes() for the services which voted for the lastCommitTime
around which a consensus was formed.
• If this quorum member is joined with the quorum it will have observed its own QuorumStateChangeListener.memberAdd(), QuorumStateChangeListener.pipelineAdd(), QuorumStateChangeListener.consensus(long), and QuorumStateChangeListener.serviceJoin() events.
• The joined services will be arranged in a write pipeline, with the leader at the head of that pipeline.

When control returns from this method, the following post-conditions should be true:

• The service should be prepared to accept reads.
• If the service was elected as the quorum leader, then it should be prepared to accept writes.

If the QuorumMember is joined with the quorum but it can not satisfy these post-conditions, then it must leave the Quorum.

Specified by:

quorumMeet in interface QuorumStateChangeListener

Parameters:

token - The newly assigned quorum token.

leaderId - The UUID of the service which was elected to be the quorum leader. This information is only valid for the scope of the accompanying quorum token. (The leaderId may be obtained from #getLeader(long) at any time for a met quorum.)