AbstractQuorum.QuorumActorBase (Blazegraph Database Platform 2.1.5 API)

java.lang.Object
- com.bigdata.quorum.AbstractQuorum.QuorumActorBase

All Implemented Interfaces:

QuorumActor<S,C>

Direct Known Subclasses:

MockQuorumFixture.MockQuorum.MockQuorumActor

Enclosing class:

AbstractQuorum<S extends Remote,C extends QuorumClient<S>>
```
protected abstract class AbstractQuorum.QuorumActorBase
extends Object
implements QuorumActor<S,C>
```
Base class for QuorumActor implementations. The methods on this base class are designed maintain certain invariants in the distributed, both for this service and (in the case of forcing a pipeline leave on another service) for other services.
This class does NOT cause changes in the local AbstractQuorum state directly. Instead, it makes changes to the distributed quorum state which are perceived by the AbstractQuorum.QuorumWatcherBase, which makes the corresponding adjustments to the AbstractQuorum's internal state.
In order to provide the postcondition guarantee for actions that the change has been made to the distributed quorum state, the QuorumActor awaits an appropriate Condition on the AbstractQuorum and then verifies that the desired state change has occurred. This mechanism relies on the asynchronous perception of the change in the distributed quorum state by the paired AbstractQuorum.QuorumWatcherBase and its update of the internal state maintained on the AbstractQuorum.
Note: It is not possible in a distributed system to guarantee that state changes made by other processes will not conflict with those which are made by this actor on the behalf of its service. However, outside of rare cases such as forcing another service to withdraw from the pipeline, all services act solely on their own facet of the distributed quorum state and all state changes are those which can be made atomic using a suitable distributed state system, such as zookeeper.
Public API Implementation Notes
This base class implements the public API and delegates each public method to a protected abstract method which must be implemented by the concrete class. The public methods are final and encapsulate the logic to maintain the invariants for the distributed quorum state. The abstract protected methods must embody the logic required to effect those distributed state changes. All such state changes MUST be atomic. Since we will be invoking the public APIs for other operations, the public API methods should only log messages if the actor will do something.
Everything is done while holding the AbstractQuorum.lock. Since each service only acts on itself, the distributed state should remain consistent. The AbstractQuorum and the AbstractQuorum.QuorumActorBase both rely on the AbstractQuorums internal image of the distributed quorum state, which is maintained by the AbstractQuorum.QuorumWatcherBase.
Public API "Add" methods
The "add" methods are those operations which add something to the distributed quorum state, such as adding a member service, adding a service to the pipeline, casting a vote, or a service join.
The public API "add" methods follow a pattern which rejects operations if the preconditions for the action are not met while holding the AbstractQuorum.lock. For example, a service can not "join" unless it is a member, has cast a vote, there is a consensus for that vote, and the service is part of the pipeline. The detailed preconditions are documented on the QuorumActor.
Public API "Remove" methods
The "remove" methods are those operations which retract something from the distributed quorum state, such as a service leave, a pipeline leave, withdrawing a vote cast by a member service, and removing a member service from the quorum.
The public API "remove" methods follow a pattern which retracts any other information which must be retracted as a precondition before the specified retraction may be applied. These preconditions are evaluated while holding the AbstractQuorum.lock. Likewise, the actions are taken while holding that lock. Since the AbstractQuorum.QuorumWatcherBase must obtain the lock in order to update the AbstractQuorum's internal state, the internal state of the AbstractQuorum will not (in general) update until after the public API method releases the lock (this might not be true for the within JVM mock objects since the watcher can run in the same thread as the actor).
For example, the public API member remove operation is implemented as follows. If, while holding the lock, the service is a member, then the operation delegates to each of the other public API methods to remove it from the joined services, the pipeline, and withdraw its votes. Finally, the public memberRemove() method invokes the protected method doMemberRemove() method to actually remove the service from the set of member services in the distributed quorum state.
The public API methods all use conditional logic to cut down on remote operations if the AbstractQuorum's internal state shows that the service is not a member, not in the pipeline, has not cast a vote, etc.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected class AbstractQuorum.QuorumActorBase.ActorTask
Task used to run an action.

Nested Classes
Modifier and Type	Class and Description
`protected class`	`AbstractQuorum.QuorumActorBase.ActorTask` Task used to run an action.

Field Summary

Fields
Modifier and Type Field and Description

protected String logicalServiceId

protected UUID serviceId

Fields
Modifier and Type	Field and Description
`protected String`	`logicalServiceId`
`protected UUID`	`serviceId`

Constructor Summary

Constructors
Modifier Constructor and Description

protected AbstractQuorum.QuorumActorBase(String logicalServiceId, UUID serviceId)

Constructors
Modifier	Constructor and Description
`protected`	`AbstractQuorum.QuorumActorBase(String logicalServiceId, UUID serviceId)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`castVote(long lastCommitTime)` Cast a vote on the behalf of the associated service.
`void`	`clearToken()` Clear the quorum token.
`protected abstract void`	`doCastVote(long lastCommitTime)`
`protected abstract void`	`doClearToken()`
`protected abstract void`	`doMemberAdd()`
`protected void`	`doMemberRemove()`
`protected abstract void`	`doMemberRemove(UUID serviceId)`
`protected abstract void`	`doPipelineAdd()`
`protected void`	`doPipelineRemove()`
`protected abstract void`	`doPipelineRemove(UUID serviceId)`
`protected abstract void`	`doServiceJoin()`
`protected void`	`doServiceLeave()`
`protected abstract void`	`doServiceLeave(UUID serviceId)`
`protected abstract void`	`doSetToken(long newToken)`
`protected void`	`doWithdrawVote()`
`protected abstract void`	`doWithdrawVote(UUID serviceId)`
`void`	`forceRemoveService(UUID psid)` Remove the service from the quorum.
`QuorumMember<S>`	`getQuorumMember()` The service on whose behalf this class is acting.
`Quorum<S,C>`	`getQuourm()` The `Quorum`.
`UUID`	`getServiceId()` The `UUID` of the service on whose behalf this class is acting.
`void`	`memberAdd()` Add the service to the set of quorum members.
`void`	`memberRemove()` Remove the service from the set of quorum members.
`void`	`pipelineAdd()` Add the service to the write pipeline.
`void`	`pipelineRemove()` Remove the service from the write pipeline.
`protected boolean`	`reorganizePipeline()` Invoked when our client will become the leader to (a) reorganize the write pipeline such that our client is the first service in the write pipeline (the leader MUST be the first service in the write pipeline); and (b) to optionally optimize the write pipeline for the network topology.
`void`	`serviceJoin()` Add the associated service to the set of joined services for the quorum.
`void`	`serviceLeave()` Remove the associated service from the set of joined services for the quorum.
`void`	`setToken(long newToken)` Atomically set the lastValidToken and the current token on the quorum equal to the given token.
`void`	`withdrawVote()` Withdraw the vote cast by the service (a service has only one vote).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - logicalServiceId
```
protected final String logicalServiceId
```
  - serviceId
```
protected final UUID serviceId
```
- Constructor Detail
  - AbstractQuorum.QuorumActorBase
```
protected AbstractQuorum.QuorumActorBase(String logicalServiceId,
                              UUID serviceId)
```
    Parameters:
    logicalServiceId - The identifier of the logical service.
    serviceId - The UUID of the physical service.
- Method Detail
  - getQuorumMember
```
public final QuorumMember<S> getQuorumMember()
```
    Description copied from interface: QuorumActor
    
    The service on whose behalf this class is acting.
    
    Specified by:
    
    getQuorumMember in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - getQuourm
```
public final Quorum<S,C> getQuourm()
```
    Description copied from interface: QuorumActor
    
    The Quorum.
    
    Specified by:
    
    getQuourm in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - getServiceId
```
public final UUID getServiceId()
```
    Description copied from interface: QuorumActor
    
    The UUID of the service on whose behalf this class is acting.
    
    Specified by:
    
    getServiceId in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - memberAdd
```
public final void memberAdd()
```
    Description copied from interface: QuorumActor
    
    Add the service to the set of quorum members.
    
    Specified by:
    
    memberAdd in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - castVote
```
public final void castVote(long lastCommitTime)
```
    Description copied from interface: QuorumActor
    
    Cast a vote on the behalf of the associated service. If the service is not part of the pipeline, then it is implicitly added to the pipeline. If the service has already voted for some other lastCommitTime, then that vote is withdrawn before the new vote is cast. Services do not withdraw their cast votes until a quorum breaks and a new consensus needs to be established. When it does, then need to consult their root blocks and vote their then current lastCommitTime.
    When a service needs to re-synchronize with a quorum, it initially votes its current lastCommitTime. Once the service is receiving writes from the write pipeline and has synchronized any historical delta, it will update its vote and join the quorum at the next commit point (or immediately if there are no outstanding writes against the quorum).
    
    Specified by:
    
    castVote in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
    
    Parameters:
    lastCommitTime - The lastCommitTime timestamp for which the service casts its vote.
  - pipelineAdd
```
public final void pipelineAdd()
```
    Description copied from interface: QuorumActor
    
    Add the service to the write pipeline.
    
    Specified by:
    
    pipelineAdd in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - serviceJoin
```
public final void serviceJoin()
```
    Description copied from interface: QuorumActor
    
    Add the associated service to the set of joined services for the quorum.
    
    Specified by:
    
    serviceJoin in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - setToken
```
public final void setToken(long newToken)
```
    Description copied from interface: QuorumActor
    
    Atomically set the lastValidToken and the current token on the quorum equal to the given token. This method is invoked when the leader is elected, passing in newToken := lastValidToken + 1.
    
    Specified by:
    
    setToken in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - clearToken
```
public final void clearToken()
```
    Description copied from interface: QuorumActor
    
    Clear the quorum token.
    
    Specified by:
    
    clearToken in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - memberRemove
```
public final void memberRemove()
```
    Description copied from interface: QuorumActor
    
    Remove the service from the set of quorum members.
    
    Specified by:
    
    memberRemove in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - withdrawVote
```
public final void withdrawVote()
```
    Description copied from interface: QuorumActor
    
    Withdraw the vote cast by the service (a service has only one vote).
    
    Specified by:
    
    withdrawVote in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - pipelineRemove
```
public final void pipelineRemove()
```
    Description copied from interface: QuorumActor
    
    Remove the service from the write pipeline.
    
    Specified by:
    
    pipelineRemove in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - serviceLeave
```
public final void serviceLeave()
```
    Description copied from interface: QuorumActor
    
    Remove the associated service from the set of joined services for the quorum.
    
    Specified by:
    
    serviceLeave in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
  - doMemberAdd
```
protected abstract void doMemberAdd()
```
  - doMemberRemove
```
protected final void doMemberRemove()
```
  - doMemberRemove
```
protected abstract void doMemberRemove(UUID serviceId)
```
  - doCastVote
```
protected abstract void doCastVote(long lastCommitTime)
```
  - doWithdrawVote
```
protected final void doWithdrawVote()
```
  - doWithdrawVote
```
protected abstract void doWithdrawVote(UUID serviceId)
```
  - doPipelineAdd
```
protected abstract void doPipelineAdd()
```
  - doPipelineRemove
```
protected final void doPipelineRemove()
```
  - doPipelineRemove
```
protected abstract void doPipelineRemove(UUID serviceId)
```
  - doServiceJoin
```
protected abstract void doServiceJoin()
```
  - doServiceLeave
```
protected final void doServiceLeave()
```
  - doServiceLeave
```
protected abstract void doServiceLeave(UUID serviceId)
```
  - doSetToken
```
protected abstract void doSetToken(long newToken)
```
  - doClearToken
```
protected abstract void doClearToken()
```
  - forceRemoveService
```
public final void forceRemoveService(UUID psid)
```
    Remove the service from the quorum. This should be called when a problem with the service is reported to the quorum leader, for example as a result of a failed RMI request or failed socket level write replication. Such errors arise either from network connectivity or service death. These problems will generally be cured, but the heatbeat timeout to cure the problem can cause write replication to block. This method may be used to force the timely reordering of the pipeline in order to work around the replication problem. This is not a permenant disabling of the service - the service may be restarted or may recover and reenter the quorum at any time.
    Note: This implements an unconditional remove of the specified service. It is intended to force a different service out of the pipeline. This code deliberately takes this action unconditionally and does NOT await the requested state change.
    Note: This code could potentially cause the remote service to deadlock in one of the conditionalXXX() methods if it is concurrently attempting to execute quorum action on itself. If this problem is observed, we should add a timeout to the conditionalXXX() methods that will force them to fail rather than block forever. This will then force the service into an error state if its QuorumActor can not carry out the requested action within a specified timeout.
    
    Specified by:
    
    forceRemoveService in interface QuorumActor<S extends Remote,C extends QuorumClient<S>>
    
    Parameters:
    psid - The UUID of the service to be removed.
    See Also:
    HA wire pulling and sure kill testing
  - reorganizePipeline
```
protected boolean reorganizePipeline()
```
    Invoked when our client will become the leader to (a) reorganize the write pipeline such that our client is the first service in the write pipeline (the leader MUST be the first service in the write pipeline); and (b) to optionally optimize the write pipeline for the network topology.
    The default implementation directs each service before this service in the write pipeline to move itself to the end of the write pipeline.
    
    Returns:
    true if the pipeline order was modified.
    See Also:
    HAPipelineGlue.moveToEndOfPipeline()

Class AbstractQuorum.QuorumActorBase

Public API Implementation Notes

Public API "Add" methods

Public API "Remove" methods

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logicalServiceId

serviceId

Constructor Detail

AbstractQuorum.QuorumActorBase

Method Detail

getQuorumMember

getQuourm

getServiceId

memberAdd

castVote

pipelineAdd

serviceJoin

setToken

clearToken

memberRemove

withdrawVote

pipelineRemove

serviceLeave

doMemberAdd

doMemberRemove

doMemberRemove

doCastVote

doWithdrawVote

doWithdrawVote

doPipelineAdd

doPipelineRemove

doPipelineRemove

doServiceJoin

doServiceLeave

doServiceLeave

doSetToken

doClearToken

forceRemoveService

reorganizePipeline