org.opendaylight.controller.cluster.raft

Class RaftActor

java.lang.Object

akka.actor.UntypedActor

akka.persistence.UntypedPersistentActor

org.opendaylight.controller.cluster.common.actor.AbstractUntypedPersistentActor

org.opendaylight.controller.cluster.raft.RaftActor

All Implemented Interfaces:

akka.actor.Actor, akka.actor.Stash, akka.actor.StashFactory, akka.actor.StashSupport, akka.actor.UnrestrictedStash, akka.dispatch.RequiresMessageQueue<akka.dispatch.DequeBasedMessageQueueSemantics>, akka.persistence.Eventsourced, akka.persistence.PersistenceIdentity, akka.persistence.PersistenceRecovery, akka.persistence.PersistenceStash, akka.persistence.Snapshotter, ExecuteInSelfActor

Direct Known Subclasses:

ExampleActor, Shard

public abstract class RaftActor
extends AbstractUntypedPersistentActor

RaftActor encapsulates a state machine that needs to be kept synchronized in a cluster. It implements the RAFT algorithm as described in the paper In Search of an Understandable Consensus Algorithm

RaftActor has 3 states and each state has a certain behavior associated with it. A Raft actor can behave as,

• A Leader
• A Follower (or)
• A Candidate

A RaftActor MUST be a Leader in order to accept requests from clients to change the state of it's encapsulated state machine. Once a RaftActor becomes a Leader it is also responsible for ensuring that all followers ultimately have the same log and therefore the same state machine as itself.

The current behavior of a RaftActor determines how election for leadership is initiated and how peer RaftActors react to request for votes.

Each RaftActor also needs to know the current election term. It uses this information for a couple of things. One is to simply figure out who it voted for in the last election. Another is to figure out if the message it received to update it's state is stale.

The RaftActor uses akka-persistence to store it's replicated log. Furthermore through it's behaviors a Raft Actor determines

• when a log entry should be persisted
• when a log entry should be applied to the state machine (and)
• when a snapshot should be saved

Nested Class Summary

Nested classes/interfaces inherited from interface akka.persistence.Eventsourced

akka.persistence.Eventsourced.AsyncHandlerInvocation, akka.persistence.Eventsourced.AsyncHandlerInvocation$, akka.persistence.Eventsourced.PendingHandlerInvocation, akka.persistence.Eventsourced.ProcessingState, akka.persistence.Eventsourced.RecoveryTick, akka.persistence.Eventsourced.RecoveryTick$, akka.persistence.Eventsourced.StashingHandlerInvocation, akka.persistence.Eventsourced.StashingHandlerInvocation$, akka.persistence.Eventsourced.State

Nested classes/interfaces inherited from interface akka.actor.Actor

akka.actor.Actor.emptyBehavior$, akka.actor.Actor.ignoringBehavior$

Field Summary

Fields inherited from class org.opendaylight.controller.cluster.common.actor.AbstractUntypedPersistentActor

LOG

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RaftActor(String id, Map<String,String> peerAddresses, com.google.common.base.Optional<ConfigParams> configParams, short payloadVersion)

Method Summary

Modifier and Type	Method and Description
protected abstract void	applyState(akka.actor.ActorRef clientActor, org.opendaylight.yangtools.concepts.Identifier identifier, Object data) The applyState method will be called by the RaftActor when some data needs to be applied to the actor's state.
protected void	changeCurrentBehavior(RaftActorBehavior newBehavior)
protected RaftActorBehavior	getCurrentBehavior()
protected Long	getCurrentTerm()
protected String	getId()
akka.actor.ActorSelection	getLeader() Derived actor can call getLeader if they need a reference to the Leader.
protected String	getLeaderId() Returns the id of the current leader.
protected RaftActorContext	getRaftActorContext()
protected abstract RaftActorRecoveryCohort	getRaftActorRecoveryCohort() Returns the RaftActorRecoveryCohort to participate in persistence recovery.
protected abstract RaftActorSnapshotCohort	getRaftActorSnapshotCohort() Returns the RaftActorSnapshotCohort to participate in snapshot captures.
protected RaftState	getRaftState()
protected abstract com.google.common.base.Optional<akka.actor.ActorRef>	getRoleChangeNotifier() Notifier Actor for this RaftActor to notify when a role change happens.
protected void	handleCommand(Object message) Deprecated. This method is not final for testing purposes. DO NOT OVERRIDE IT, override handleNonRaftCommand(Object) instead.
protected void	handleNonRaftCommand(Object message) Method exposed for subclasses to plug-in their logic.
protected void	handleRecover(Object message)
protected boolean	hasFollowers()
protected boolean	isLeader() Derived actors can call the isLeader method to check if the current RaftActor is the Leader or not.
protected boolean	isLeaderActive()
protected boolean	isLeadershipTransferInProgress()
protected LeaderStateChanged	newLeaderStateChanged(String memberId, String leaderId, short leaderPayloadVersion)
protected OnDemandRaftState.AbstractBuilder<?,?>	newOnDemandRaftStateBuilder()
protected org.opendaylight.controller.cluster.raft.RaftActorRecoverySupport	newRaftActorRecoverySupport()
protected void	onLeaderChanged(String oldLeader, String newLeader)
protected abstract void	onRecoveryComplete() This method is called when recovery is complete.
protected abstract void	onStateChanged() This method will be called by the RaftActor when the state of the RaftActor changes.
protected void	onVotingStateChangeComplete() This method is called on the leader when a voting change operation completes.
protected void	pauseLeader(Runnable operation) This method is called prior to operations such as leadership transfer and actor shutdown when the leader must pause or stop its duties.
protected void	persistData(akka.actor.ActorRef clientActor, org.opendaylight.yangtools.concepts.Identifier identifier, Payload data, boolean batchHint) Persists the given Payload in the journal and replicates to any followers.
DataPersistenceProvider	persistence()
void	postStop()
void	preStart()
protected void	setPeerAddress(String peerId, String peerAddress) setPeerAddress sets the address of a known peer at a later time.
protected void	setPersistence(boolean persistent)
void	setPersistence(DataPersistenceProvider provider)
long	snapshotSequenceNr()
protected void	unpauseLeader() This method is invoked when the actions hooked to the leader becoming paused failed to execute and the leader should resume normal operations.
protected void	updateConfigParams(ConfigParams configParams)

Methods inherited from class org.opendaylight.controller.cluster.common.actor.AbstractUntypedPersistentActor

executeInSelf, ignoreMessage, onReceiveCommand, onReceiveRecover, unknownMessage

Methods inherited from class akka.persistence.UntypedPersistentActor

akka$actor$StashSupport$_setter_$akka$actor$StashSupport$$capacity_$eq, akka$actor$StashSupport$_setter_$mailbox_$eq, akka$actor$StashSupport$$capacity, akka$actor$StashSupport$$theStash_$eq, akka$actor$StashSupport$$theStash, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$extension_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$instanceId_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$internalStash_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$maxMessageBatchSize_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$pendingInvocations_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$persistingEvents_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$processingCommands_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$unstashFilterPredicate_$eq, akka$persistence$Eventsourced$_setter_$akka$persistence$Eventsourced$$writerUuid_$eq, akka$persistence$Eventsourced$$_lastSequenceNr_$eq, akka$persistence$Eventsourced$$_lastSequenceNr, akka$persistence$Eventsourced$$currentState_$eq, akka$persistence$Eventsourced$$currentState, akka$persistence$Eventsourced$$eventBatch_$eq, akka$persistence$Eventsourced$$eventBatch, akka$persistence$Eventsourced$$extension, akka$persistence$Eventsourced$$instanceId, akka$persistence$Eventsourced$$internalStash, akka$persistence$Eventsourced$$journalBatch_$eq, akka$persistence$Eventsourced$$journalBatch, akka$persistence$Eventsourced$$maxMessageBatchSize, akka$persistence$Eventsourced$$pendingInvocations, akka$persistence$Eventsourced$$pendingStashingPersistInvocations_$eq, akka$persistence$Eventsourced$$pendingStashingPersistInvocations, akka$persistence$Eventsourced$$persistingEvents, akka$persistence$Eventsourced$$processingCommands, akka$persistence$Eventsourced$$sequenceNr_$eq, akka$persistence$Eventsourced$$sequenceNr, akka$persistence$Eventsourced$$unstashFilterPredicate, akka$persistence$Eventsourced$$writeInProgress_$eq, akka$persistence$Eventsourced$$writeInProgress, akka$persistence$Eventsourced$$writerUuid, aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, clearStash, createStash, deferAsync, deleteMessages, deleteSnapshot, deleteSnapshots, internalDeferAsync, internalPersist, internalPersistAll, internalPersistAllAsync, internalPersistAsync, internalStashOverflowStrategy, journal, journalPluginId, lastSequenceNr, loadSnapshot, mailbox, onPersistFailure, onPersistRejected, onReceive, onRecoveryFailure, onReplaySuccess, persist, persistAll, persistAllAsync, persistAsync, prepend, preRestart, receiveCommand, receiveRecover, recovery, recoveryFinished, recoveryRunning, saveSnapshot, snapshotPluginId, snapshotStore, snapshotterId, stash, unhandled, unstash, unstashAll, unstashAll

Methods inherited from class akka.actor.UntypedActor

akka$actor$Actor$_setter_$context_$eq, akka$actor$Actor$_setter_$self_$eq, context, getContext, getSelf, getSender, postRestart, receive, self, sender, supervisorStrategy

Methods inherited from class java.lang.Object

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

Methods inherited from interface akka.persistence.Eventsourced

$init$, akka$persistence$Eventsourced$$changeState, akka$persistence$Eventsourced$$flushBatch, akka$persistence$Eventsourced$$flushJournalBatch, akka$persistence$Eventsourced$$peekApplyHandler, akka$persistence$Eventsourced$$recovering, akka$persistence$Eventsourced$$setLastSequenceNr, akka$persistence$Eventsourced$$startRecovery, akka$persistence$Eventsourced$$stashInternally, akka$persistence$Eventsourced$$unstashInternally, akka$persistence$Eventsourced$$updateLastSequenceNr

Methods inherited from interface akka.persistence.Snapshotter

$init$

Methods inherited from interface akka.persistence.PersistenceStash

$init$

Methods inherited from interface akka.actor.UnrestrictedStash

$init$

Methods inherited from interface akka.actor.Actor

$init$, akka$actor$Actor$_setter_$context_$eq, akka$actor$Actor$_setter_$self_$eq, context, noSender, postRestart, receive, self, sender, supervisorStrategy

Methods inherited from interface akka.actor.StashSupport

$init$, context, self

Methods inherited from interface akka.actor.StashFactory

$init$

Methods inherited from interface akka.persistence.PersistenceIdentity

$init$, persistenceId

Methods inherited from interface akka.persistence.PersistenceRecovery

$init$

Constructor Detail

RaftActor

protected RaftActor(String id,
                    Map<String,String> peerAddresses,
                    com.google.common.base.Optional<ConfigParams> configParams,
                    short payloadVersion)

Method Detail

preStart

public void preStart()
              throws Exception

Specified by:

preStart in interface akka.actor.Actor

Overrides:

preStart in class akka.actor.UntypedActor

Throws:

Exception

postStop

public void postStop()

Specified by:

postStop in interface akka.actor.Actor

Specified by:

postStop in interface akka.actor.UnrestrictedStash

Overrides:

postStop in class akka.persistence.UntypedPersistentActor

handleRecover

protected void handleRecover(Object message)

Specified by:

handleRecover in class AbstractUntypedPersistentActor

newRaftActorRecoverySupport

protected org.opendaylight.controller.cluster.raft.RaftActorRecoverySupport newRaftActorRecoverySupport()

changeCurrentBehavior

protected void changeCurrentBehavior(RaftActorBehavior newBehavior)

handleNonRaftCommand

protected void handleNonRaftCommand(Object message)

Method exposed for subclasses to plug-in their logic. This method is invoked by handleCommand(Object) for messages which are not handled by this class. Subclasses overriding this class should fall back to this implementation for messages which they do not handle

Parameters:

message - Incoming command message

handleCommand

@Deprecated
protected void handleCommand(Object message)

Deprecated. This method is not final for testing purposes. DO NOT OVERRIDE IT, override handleNonRaftCommand(Object) instead.

Handles a message.

Specified by:

handleCommand in class AbstractUntypedPersistentActor

newOnDemandRaftStateBuilder

protected OnDemandRaftState.AbstractBuilder<?,?> newOnDemandRaftStateBuilder()

newLeaderStateChanged

protected LeaderStateChanged newLeaderStateChanged(String memberId,
                                                   String leaderId,
                                                   short leaderPayloadVersion)

snapshotSequenceNr

public long snapshotSequenceNr()

Specified by:

snapshotSequenceNr in interface akka.persistence.Eventsourced

Specified by:

snapshotSequenceNr in interface akka.persistence.Snapshotter

Overrides:

snapshotSequenceNr in class akka.persistence.UntypedPersistentActor

persistData

protected final void persistData(akka.actor.ActorRef clientActor,
                                 org.opendaylight.yangtools.concepts.Identifier identifier,
                                 Payload data,
                                 boolean batchHint)

Persists the given Payload in the journal and replicates to any followers. After successful completion, applyState(ActorRef, Identifier, Object) is notified.

Parameters:

clientActor - optional ActorRef that is provided via the applyState callback

identifier - the payload identifier

data - the payload data to persist

batchHint - if true, an attempt is made to delay immediate replication and batch the payload with subsequent payloads for efficiency. Otherwise the payload is immediately replicated.

getId

protected String getId()

getCurrentBehavior

protected RaftActorBehavior getCurrentBehavior()

isLeader

protected boolean isLeader()

Derived actors can call the isLeader method to check if the current RaftActor is the Leader or not.

Returns:

true it this RaftActor is a Leader false otherwise

isLeaderActive

protected final boolean isLeaderActive()

isLeadershipTransferInProgress

protected boolean isLeadershipTransferInProgress()

getLeader

public akka.actor.ActorSelection getLeader()

Derived actor can call getLeader if they need a reference to the Leader. This would be useful for example in forwarding a request to an actor which is the leader

Returns:

A reference to the leader if known, null otherwise

getLeaderId

protected final String getLeaderId()

Returns the id of the current leader.

Returns:

the current leader's id

getRaftState

protected final RaftState getRaftState()

getCurrentTerm

protected Long getCurrentTerm()

getRaftActorContext

protected RaftActorContext getRaftActorContext()

updateConfigParams

protected void updateConfigParams(ConfigParams configParams)

persistence

public final DataPersistenceProvider persistence()

setPersistence

public void setPersistence(DataPersistenceProvider provider)

setPersistence

protected void setPersistence(boolean persistent)

setPeerAddress

protected void setPeerAddress(String peerId,
                              String peerAddress)

setPeerAddress sets the address of a known peer at a later time.

This is to account for situations where a we know that a peer exists but we do not know an address up-front. This may also be used in situations where a known peer starts off in a different location and we need to change it's address

Note that if the peerId does not match the list of peers passed to this actor during construction an IllegalStateException will be thrown.

applyState

protected abstract void applyState(akka.actor.ActorRef clientActor,
                                   org.opendaylight.yangtools.concepts.Identifier identifier,
                                   Object data)

The applyState method will be called by the RaftActor when some data needs to be applied to the actor's state.

Parameters:

clientActor - A reference to the client who sent this message. This is the same reference that was passed to persistData by the derived actor. clientActor may be null when the RaftActor is behaving as a follower or during recovery.

identifier - The identifier of the persisted data. This is also the same identifier that was passed to persistData by the derived actor. identifier may be null when the RaftActor is behaving as a follower or during recovery

data - A piece of data that was persisted by the persistData call. This should NEVER be null.

getRaftActorRecoveryCohort

@Nonnull
protected abstract RaftActorRecoveryCohort getRaftActorRecoveryCohort()

Returns the RaftActorRecoveryCohort to participate in persistence recovery.

onRecoveryComplete

protected abstract void onRecoveryComplete()

This method is called when recovery is complete.

getRaftActorSnapshotCohort

@Nonnull
protected abstract RaftActorSnapshotCohort getRaftActorSnapshotCohort()

Returns the RaftActorSnapshotCohort to participate in snapshot captures.

onStateChanged

protected abstract void onStateChanged()

This method will be called by the RaftActor when the state of the RaftActor changes. The derived actor can then use methods like isLeader or getLeader to do something useful

getRoleChangeNotifier

protected abstract com.google.common.base.Optional<akka.actor.ActorRef> getRoleChangeNotifier()

Notifier Actor for this RaftActor to notify when a role change happens.

Returns:

ActorRef - ActorRef of the notifier or Optional.absent if none.

onVotingStateChangeComplete

protected void onVotingStateChangeComplete()

This method is called on the leader when a voting change operation completes.

pauseLeader

protected void pauseLeader(Runnable operation)

This method is called prior to operations such as leadership transfer and actor shutdown when the leader must pause or stop its duties. This method allows derived classes to gracefully pause or finish current work prior to performing the operation. On completion of any work, the run method must be called on the given Runnable to proceed with the given operation. Important: the run method must be called on this actor's thread dispatcher as as it modifies internal state.

The default implementation immediately runs the operation.

Parameters:

operation - the operation to run

unpauseLeader

protected void unpauseLeader()

This method is invoked when the actions hooked to the leader becoming paused failed to execute and the leader should resume normal operations.

Note this method can be invoked even before the operation supplied to pauseLeader(Runnable) is invoked.

onLeaderChanged

protected void onLeaderChanged(String oldLeader,
                               String newLeader)

hasFollowers

protected boolean hasFollowers()