* terms of the Eclipse Public License v1.0 which accompanies this distribution,
* and is available at http://www.eclipse.org/legal/epl-v10.html
*/
-
package org.opendaylight.controller.cluster.raft;
import akka.actor.ActorRef;
import akka.actor.ActorSelection;
import akka.actor.ActorSystem;
import akka.actor.Props;
-import akka.event.LoggingAdapter;
-
-import java.util.Map;
+import akka.cluster.Cluster;
+import com.google.common.annotations.VisibleForTesting;
+import java.util.Collection;
+import java.util.Optional;
+import java.util.concurrent.Executor;
+import java.util.function.Consumer;
+import java.util.function.LongSupplier;
+import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
+import org.opendaylight.controller.cluster.DataPersistenceProvider;
+import org.opendaylight.controller.cluster.io.FileBackedOutputStreamFactory;
+import org.opendaylight.controller.cluster.raft.base.messages.ApplyState;
+import org.opendaylight.controller.cluster.raft.behaviors.RaftActorBehavior;
+import org.opendaylight.controller.cluster.raft.persisted.ServerConfigurationPayload;
+import org.opendaylight.controller.cluster.raft.policy.RaftPolicy;
+import org.slf4j.Logger;
/**
* The RaftActorContext contains that portion of the RaftActors state that
*/
public interface RaftActorContext {
/**
- * Create a new local actor
- * @param props
- * @return
+ * Creates a new local actor.
+ *
+ * @param props the Props used to create the actor.
+ * @return a reference to the newly created actor.
*/
ActorRef actorOf(Props props);
/**
- * Create a actor selection
- * @param path
- * @return
+ * Creates an actor selection.
+ *
+ * @param path the path.
+ * @return an actor selection for the given actor path.
*/
ActorSelection actorSelection(String path);
/**
- * Get the identifier for the RaftActor. This identifier represents the
- * name of the actor whose common state is being shared. For example the
- * id could be 'inventory'
+ * Returns the identifier for the RaftActor. This identifier represents the
+ * name of the actor whose common state is being shared.
+ *
* @return the identifier
*/
String getId();
/**
- * A reference to the RaftActor itself. This could be used to send messages
- * to the RaftActor
- * @return
+ * Returns the reference to the RaftActor.
+ *
+ * @return the reference to the RaftActor itself. This can be used to send messages to the RaftActor
*/
ActorRef getActor();
/**
- * Get the ElectionTerm information
- * @return
+ * Return an Executor which is guaranteed to run tasks in the context of {@link #getActor()}.
+ *
+ * @return An executor.
*/
- ElectionTerm getTermInformation();
+ @NonNull Executor getExecutor();
/**
- * index of highest log entry known to be
- * committed (initialized to 0, increases
- * monotonically)
- * @return
+ * The akka Cluster singleton for the actor system if one is configured.
+ *
+ * @return an Optional containing the Cluster instance is present.
+ */
+ Optional<Cluster> getCluster();
+
+ /**
+ * Returns the current ElectionTerm information.
+ *
+ * @return the ElectionTerm.
+ */
+ @NonNull ElectionTerm getTermInformation();
+
+ /**
+ * Returns the index of highest log entry known to be committed.
+ *
+ * @return index of highest log entry known to be committed.
*/
long getCommitIndex();
/**
+ * Sets the index of highest log entry known to be committed.
*
+ * @param commitIndex new commit index
*/
void setCommitIndex(long commitIndex);
/**
- * index of highest log entry applied to state
- * machine (initialized to 0, increases
- * monotonically)
- * @return
+ * Returns index of highest log entry applied to state machine.
+ *
+ * @return index of highest log entry applied to state machine.
*/
long getLastApplied();
-
/**
+ * Sets index of highest log entry applied to state machine.
*
+ * @param lastApplied the new applied index.
*/
void setLastApplied(long lastApplied);
/**
+ * Sets the ReplicatedLog instance.
*
- * @param replicatedLog
+ * @param replicatedLog the ReplicatedLog instance.
*/
- public void setReplicatedLog(ReplicatedLog replicatedLog);
+ void setReplicatedLog(@NonNull ReplicatedLog replicatedLog);
/**
- * @return A representation of the log
+ * Returns the ReplicatedLog instance.
+ *
+ * @return the ReplicatedLog instance.
*/
- ReplicatedLog getReplicatedLog();
+ @NonNull ReplicatedLog getReplicatedLog();
/**
- * @return The ActorSystem associated with this context
+ * Returns the The ActorSystem associated with this context.
+ *
+ * @return the ActorSystem.
*/
- ActorSystem getActorSystem();
+ @NonNull ActorSystem getActorSystem();
/**
- * Get the logger to be used for logging messages
+ * Returns the logger to be used for logging messages.
*
- * @return
+ * @return the logger.
*/
- LoggingAdapter getLogger();
+ @NonNull Logger getLogger();
/**
- * Get a mapping of peerId's to their addresses
+ * Gets the address of a peer as a String. This is the same format in which a consumer would provide the address.
*
- * @return
+ * @param peerId the id of the peer.
+ * @return the address of the peer or null if the address has not yet been resolved.
+ */
+ @Nullable String getPeerAddress(String peerId);
+
+ /**
+ * Updates the peers and information to match the given ServerConfigurationPayload.
*
+ * @param serverCfgPayload the ServerConfigurationPayload.
*/
- Map<String, String> getPeerAddresses();
+ void updatePeerIds(ServerConfigurationPayload serverCfgPayload);
/**
- * Get the address of the peer as a String. This is the same format in
- * which a consumer would provide the address
+ * Returns the PeerInfo instances for each peer.
*
- * @param peerId
- * @return The address of the peer or null if the address has not yet been
- * resolved
+ * @return list of PeerInfo
*/
- String getPeerAddress(String peerId);
+ @NonNull Collection<PeerInfo> getPeers();
/**
- * Add to actor peers
- * @param name
- * @param address
+ * Returns the id's for each peer.
+ *
+ * @return the list of peer id's.
*/
- void addToPeers(String name, String address);
+ @NonNull Collection<String> getPeerIds();
/**
+ * Returns the PeerInfo for the given peer.
*
- * @param name
+ * @param peerId the id of the peer
+ * @return the PeerInfo or null if not found
*/
- public void removePeer(String name);
+ @Nullable PeerInfo getPeerInfo(String peerId);
/**
- * Given a peerId return the corresponding actor
- * <p>
+ * Adds a new peer.
*
+ * @param id the id of the new peer.
+ * @param address the address of the new peer.
+ * @param votingState the VotingState of the new peer.
+ */
+ void addToPeers(String id, String address, VotingState votingState);
+
+ /**
+ * Removes a peer.
*
- * @param peerId
- * @return The actorSelection corresponding to the peer or null if the
- * address has not yet been resolved
+ * @param id the id of the peer to remove.
*/
- ActorSelection getPeerActorSelection(String peerId);
+ void removePeer(String id);
/**
- * Set Peer Address can be called at a later time to change the address of
- * a known peer.
+ * Returns an ActorSelection for a peer.
*
- * <p>
- * Throws an IllegalStateException if the peer is unknown
+ * @param peerId the id of the peer.
+ * @return the actorSelection corresponding to the peer or null if the address has not yet been resolved.
+ */
+ @Nullable ActorSelection getPeerActorSelection(String peerId);
+
+ /**
+ * Sets the address of a peer.
*
- * @param peerId
- * @param peerAddress
+ * @param peerId the id of the peer.
+ * @param peerAddress the address of the peer.
*/
void setPeerAddress(String peerId, String peerAddress);
/**
- * @return ConfigParams
+ * Returns the ConfigParams instance.
+ *
+ * @return the ConfigParams instance.
+ */
+ @NonNull ConfigParams getConfigParams();
+
+ /**
+ * Returns the SnapshotManager instance.
+ *
+ * @return the SnapshotManager instance.
+ */
+ @NonNull SnapshotManager getSnapshotManager();
+
+ /**
+ * Returns the DataPersistenceProvider instance.
+ *
+ * @return the DataPersistenceProvider instance.
+ */
+ @NonNull DataPersistenceProvider getPersistenceProvider();
+
+ /**
+ * Determines if there are any peer followers.
+ *
+ * @return true if there are followers otherwise false.
+ */
+ boolean hasFollowers();
+
+ /**
+ * Returns the total available memory for use in calculations. Normally this returns JVM's max memory but can be
+ * overridden for unit tests.
+ *
+ * @return the total memory.
+ */
+ long getTotalMemory();
+
+ /**
+ * Sets the retriever of the total memory metric.
+ *
+ * @param retriever a supplier of the total memory metric.
+ */
+ @VisibleForTesting
+ void setTotalMemoryRetriever(LongSupplier retriever);
+
+ /**
+ * Returns the payload version to be used when replicating data.
+ *
+ * @return the payload version.
+ */
+ short getPayloadVersion();
+
+ /**
+ * Returns the RaftPolicy used to determine certain Raft behaviors.
+ *
+ * @return the RaftPolicy instance.
+ */
+ @NonNull RaftPolicy getRaftPolicy();
+
+ /**
+ * Determines if there have been any dynamic server configuration changes applied.
+ *
+ * @return true if dynamic server configuration changes have been applied, false otherwise, meaning that static
+ * peer configuration is still in use.
+ */
+ boolean isDynamicServerConfigurationInUse();
+
+ /**
+ * Sets that dynamic server configuration changes have been applied.
+ */
+ void setDynamicServerConfigurationInUse();
+
+ /**
+ * Returns the peer information as a ServerConfigurationPayload if dynamic server configurations have been applied.
+ *
+ * @param includeSelf include this peer's info.
+ * @return the peer information as a ServerConfigurationPayload or null if no dynamic server configurations have
+ * been applied.
+ */
+ @Nullable ServerConfigurationPayload getPeerServerInfo(boolean includeSelf);
+
+ /**
+ * Determines if this peer is a voting member of the cluster.
+ *
+ * @return true if this peer is a voting member, false otherwise.
+ */
+ boolean isVotingMember();
+
+ /**
+ * Determines if there are any voting peers.
+ *
+ * @return true if there are any voting peers, false otherwise.
+ */
+ boolean anyVotingPeers();
+
+ /**
+ * Returns the current behavior attached to the RaftActor.
+ *
+ * @return current behavior.
+ */
+ RaftActorBehavior getCurrentBehavior();
+
+ /**
+ * Returns the consumer of ApplyState operations. This is invoked by a behavior when a log entry needs to be
+ * applied to the state.
+ *
+ * @return the Consumer
+ */
+ Consumer<ApplyState> getApplyStateConsumer();
+
+ /**
+ * Returns the {@link FileBackedOutputStreamFactory} instance with a common configuration.
+ *
+ * @return the {@link FileBackedOutputStreamFactory};
+ */
+ @NonNull FileBackedOutputStreamFactory getFileBackedOutputStreamFactory();
+
+ /**
+ * Returns the RaftActorLeadershipTransferCohort if leadership transfer is in progress.
+ *
+ * @return the RaftActorLeadershipTransferCohort if leadership transfer is in progress, null otherwise
+ */
+ @Nullable RaftActorLeadershipTransferCohort getRaftActorLeadershipTransferCohort();
+
+ /**
+ * Sets the RaftActorLeadershipTransferCohort for transferring leadership.
+ *
+ * @param leadershipTransferCohort the RaftActorLeadershipTransferCohort or null to clear the existing one
*/
- public ConfigParams getConfigParams();
+ void setRaftActorLeadershipTransferCohort(@Nullable RaftActorLeadershipTransferCohort leadershipTransferCohort);
}