2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.controller.cluster.raft;
10 import akka.actor.ActorRef;
11 import akka.actor.ActorSelection;
12 import akka.actor.ActorSystem;
13 import akka.actor.Props;
14 import akka.cluster.Cluster;
15 import com.google.common.annotations.VisibleForTesting;
16 import java.util.Collection;
17 import java.util.Optional;
18 import java.util.concurrent.Executor;
19 import java.util.function.Consumer;
20 import java.util.function.LongSupplier;
21 import org.eclipse.jdt.annotation.NonNull;
22 import org.eclipse.jdt.annotation.Nullable;
23 import org.opendaylight.controller.cluster.DataPersistenceProvider;
24 import org.opendaylight.controller.cluster.io.FileBackedOutputStreamFactory;
25 import org.opendaylight.controller.cluster.raft.base.messages.ApplyState;
26 import org.opendaylight.controller.cluster.raft.behaviors.RaftActorBehavior;
27 import org.opendaylight.controller.cluster.raft.persisted.ServerConfigurationPayload;
28 import org.opendaylight.controller.cluster.raft.policy.RaftPolicy;
29 import org.slf4j.Logger;
32 * The RaftActorContext contains that portion of the RaftActors state that
33 * needs to be shared with it's behaviors. A RaftActorContext should NEVER be
34 * used in any actor context outside the RaftActor that constructed it.
36 public interface RaftActorContext {
38 * Creates a new local actor.
40 * @param props the Props used to create the actor.
41 * @return a reference to the newly created actor.
43 ActorRef actorOf(Props props);
46 * Creates an actor selection.
48 * @param path the path.
49 * @return an actor selection for the given actor path.
51 ActorSelection actorSelection(String path);
54 * Returns the identifier for the RaftActor. This identifier represents the
55 * name of the actor whose common state is being shared.
57 * @return the identifier
62 * Returns the reference to the RaftActor.
64 * @return the reference to the RaftActor itself. This can be used to send messages to the RaftActor
69 * Return an Executor which is guaranteed to run tasks in the context of {@link #getActor()}.
71 * @return An executor.
73 @NonNull Executor getExecutor();
76 * The akka Cluster singleton for the actor system if one is configured.
78 * @return an Optional containing the Cluster instance is present.
80 Optional<Cluster> getCluster();
83 * Returns the current ElectionTerm information.
85 * @return the ElectionTerm.
87 @NonNull ElectionTerm getTermInformation();
90 * Returns the index of highest log entry known to be committed.
92 * @return index of highest log entry known to be committed.
94 long getCommitIndex();
98 * Sets the index of highest log entry known to be committed.
100 * @param commitIndex new commit index
102 void setCommitIndex(long commitIndex);
105 * Returns index of highest log entry applied to state machine.
107 * @return index of highest log entry applied to state machine.
109 long getLastApplied();
112 * Sets index of highest log entry applied to state machine.
114 * @param lastApplied the new applied index.
116 void setLastApplied(long lastApplied);
119 * Sets the ReplicatedLog instance.
121 * @param replicatedLog the ReplicatedLog instance.
123 void setReplicatedLog(@NonNull ReplicatedLog replicatedLog);
126 * Returns the ReplicatedLog instance.
128 * @return the ReplicatedLog instance.
130 @NonNull ReplicatedLog getReplicatedLog();
133 * Returns the The ActorSystem associated with this context.
135 * @return the ActorSystem.
137 @NonNull ActorSystem getActorSystem();
140 * Returns the logger to be used for logging messages.
142 * @return the logger.
144 @NonNull Logger getLogger();
147 * Gets the address of a peer as a String. This is the same format in which a consumer would provide the address.
149 * @param peerId the id of the peer.
150 * @return the address of the peer or null if the address has not yet been resolved.
152 @Nullable String getPeerAddress(String peerId);
155 * Updates the peers and information to match the given ServerConfigurationPayload.
157 * @param serverCfgPayload the ServerConfigurationPayload.
159 void updatePeerIds(ServerConfigurationPayload serverCfgPayload);
162 * Returns the PeerInfo instances for each peer.
164 * @return list of PeerInfo
166 @NonNull Collection<PeerInfo> getPeers();
169 * Returns the id's for each peer.
171 * @return the list of peer id's.
173 @NonNull Collection<String> getPeerIds();
176 * Returns the PeerInfo for the given peer.
178 * @param peerId the id of the peer
179 * @return the PeerInfo or null if not found
181 @Nullable PeerInfo getPeerInfo(String peerId);
186 * @param id the id of the new peer.
187 * @param address the address of the new peer.
188 * @param votingState the VotingState of the new peer.
190 void addToPeers(String id, String address, VotingState votingState);
195 * @param id the id of the peer to remove.
197 void removePeer(String id);
200 * Returns an ActorSelection for a peer.
202 * @param peerId the id of the peer.
203 * @return the actorSelection corresponding to the peer or null if the address has not yet been resolved.
205 @Nullable ActorSelection getPeerActorSelection(String peerId);
208 * Sets the address of a peer.
210 * @param peerId the id of the peer.
211 * @param peerAddress the address of the peer.
213 void setPeerAddress(String peerId, String peerAddress);
216 * Returns the ConfigParams instance.
218 * @return the ConfigParams instance.
220 @NonNull ConfigParams getConfigParams();
223 * Returns the SnapshotManager instance.
225 * @return the SnapshotManager instance.
227 @NonNull SnapshotManager getSnapshotManager();
230 * Returns the DataPersistenceProvider instance.
232 * @return the DataPersistenceProvider instance.
234 @NonNull DataPersistenceProvider getPersistenceProvider();
237 * Determines if there are any peer followers.
239 * @return true if there are followers otherwise false.
241 boolean hasFollowers();
244 * Returns the total available memory for use in calculations. Normally this returns JVM's max memory but can be
245 * overridden for unit tests.
247 * @return the total memory.
249 long getTotalMemory();
252 * Sets the retriever of the total memory metric.
254 * @param retriever a supplier of the total memory metric.
257 void setTotalMemoryRetriever(LongSupplier retriever);
260 * Returns the payload version to be used when replicating data.
262 * @return the payload version.
264 short getPayloadVersion();
267 * Returns the RaftPolicy used to determine certain Raft behaviors.
269 * @return the RaftPolicy instance.
271 @NonNull RaftPolicy getRaftPolicy();
274 * Determines if there have been any dynamic server configuration changes applied.
276 * @return true if dynamic server configuration changes have been applied, false otherwise, meaning that static
277 * peer configuration is still in use.
279 boolean isDynamicServerConfigurationInUse();
282 * Sets that dynamic server configuration changes have been applied.
284 void setDynamicServerConfigurationInUse();
287 * Returns the peer information as a ServerConfigurationPayload if dynamic server configurations have been applied.
289 * @param includeSelf include this peer's info.
290 * @return the peer information as a ServerConfigurationPayload or null if no dynamic server configurations have
293 @Nullable ServerConfigurationPayload getPeerServerInfo(boolean includeSelf);
296 * Determines if this peer is a voting member of the cluster.
298 * @return true if this peer is a voting member, false otherwise.
300 boolean isVotingMember();
303 * Determines if there are any voting peers.
305 * @return true if there are any voting peers, false otherwise.
307 boolean anyVotingPeers();
310 * Returns the current behavior attached to the RaftActor.
312 * @return current behavior.
314 RaftActorBehavior getCurrentBehavior();
317 * Returns the consumer of ApplyState operations. This is invoked by a behavior when a log entry needs to be
318 * applied to the state.
320 * @return the Consumer
322 Consumer<ApplyState> getApplyStateConsumer();
325 * Returns the {@link FileBackedOutputStreamFactory} instance with a common configuration.
327 * @return the {@link FileBackedOutputStreamFactory};
329 @NonNull FileBackedOutputStreamFactory getFileBackedOutputStreamFactory();
332 * Returns the RaftActorLeadershipTransferCohort if leadership transfer is in progress.
334 * @return the RaftActorLeadershipTransferCohort if leadership transfer is in progress, null otherwise
336 @Nullable RaftActorLeadershipTransferCohort getRaftActorLeadershipTransferCohort();
339 * Sets the RaftActorLeadershipTransferCohort for transferring leadership.
341 * @param leadershipTransferCohort the RaftActorLeadershipTransferCohort or null to clear the existing one
343 void setRaftActorLeadershipTransferCohort(@Nullable RaftActorLeadershipTransferCohort leadershipTransferCohort);