opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/RaftActorContext.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   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
   7  */
   8
   9 package org.opendaylight.controller.cluster.raft;
  10
  11 import akka.actor.ActorRef;
  12 import akka.actor.ActorSelection;
  13 import akka.actor.ActorSystem;
  14 import akka.actor.Props;
  15 import akka.cluster.Cluster;
  16 import com.google.common.annotations.VisibleForTesting;
  17 import java.util.Collection;
  18 import java.util.Optional;
  19 import java.util.function.Consumer;
  20 import java.util.function.LongSupplier;
  21 import javax.annotation.Nonnull;
  22 import javax.annotation.Nullable;
  23 import org.opendaylight.controller.cluster.DataPersistenceProvider;
  24 import org.opendaylight.controller.cluster.io.FileBackedOutputStream;
  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;
  30
  31 /**
  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.
  35  */
  36 public interface RaftActorContext {
  37     /**
  38      * Creates a new local actor.
  39      *
  40      * @param props the Props used to create the actor.
  41      * @return a reference to the newly created actor.
  42      */
  43     ActorRef actorOf(Props props);
  44
  45     /**
  46      * Creates an actor selection.
  47      *
  48      * @param path the path.
  49      * @return an actor selection for the given actor path.
  50      */
  51     ActorSelection actorSelection(String path);
  52
  53     /**
  54      * Returns the identifier for the RaftActor. This identifier represents the
  55      * name of the actor whose common state is being shared.
  56      *
  57      * @return the identifier
  58      */
  59     String getId();
  60
  61     /**
  62      * Returns the reference to the RaftActor.
  63      *
  64      * @return the reference to the RaftActor itself. This can be used to send messages to the RaftActor
  65      */
  66     ActorRef getActor();
  67
  68     /**
  69      * The akka Cluster singleton for the actor system if one is configured.
  70      *
  71      * @return an Optional containing the Cluster instance is present.
  72      */
  73     Optional<Cluster> getCluster();
  74
  75     /**
  76      * Returns the current ElectionTerm information.
  77      *
  78      * @return the ElectionTerm.
  79      */
  80     @Nonnull
  81     ElectionTerm getTermInformation();
  82
  83     /**
  84      * Returns the index of highest log entry known to be committed.
  85      *
  86      * @return index of highest log entry known to be committed.
  87      */
  88     long getCommitIndex();
  89
  90
  91     /**
  92      * Sets the index of highest log entry known to be committed.
  93      *
  94      * @param commitIndex new commit index
  95      */
  96     void setCommitIndex(long commitIndex);
  97
  98     /**
  99      * Returns index of highest log entry applied to state machine.
 100      *
 101      * @return index of highest log entry applied to state machine.
 102      */
 103     long getLastApplied();
 104
 105     /**
 106      * Sets index of highest log entry applied to state machine.
 107      *
 108      * @param lastApplied the new applied index.
 109      */
 110     void setLastApplied(long lastApplied);
 111
 112     /**
 113      * Sets the ReplicatedLog instance.
 114      *
 115      * @param replicatedLog the ReplicatedLog instance.
 116      */
 117     void setReplicatedLog(@Nonnull ReplicatedLog replicatedLog);
 118
 119     /**
 120      * Returns the ReplicatedLog instance.
 121      *
 122      * @return the ReplicatedLog instance.
 123      */
 124     @Nonnull
 125     ReplicatedLog getReplicatedLog();
 126
 127     /**
 128      * Returns the The ActorSystem associated with this context.
 129      *
 130      * @return the ActorSystem.
 131      */
 132     @Nonnull
 133     ActorSystem getActorSystem();
 134
 135     /**
 136      * Returns the logger to be used for logging messages.
 137      *
 138      * @return the logger.
 139      */
 140     @Nonnull
 141     Logger getLogger();
 142
 143     /**
 144      * Gets the address of a peer as a String. This is the same format in which a consumer would provide the address.
 145      *
 146      * @param peerId the id of the peer.
 147      * @return the address of the peer or null if the address has not yet been resolved.
 148      */
 149     @Nullable
 150     String getPeerAddress(String peerId);
 151
 152     /**
 153      * Updates the peers and information to match the given ServerConfigurationPayload.
 154      *
 155      * @param serverCfgPayload the ServerConfigurationPayload.
 156      */
 157     void updatePeerIds(ServerConfigurationPayload serverCfgPayload);
 158
 159     /**
 160      * Returns the PeerInfo instances for each peer.
 161      *
 162      * @return list of PeerInfo
 163      */
 164     @Nonnull
 165     Collection<PeerInfo> getPeers();
 166
 167     /**
 168      * Returns the id's for each peer.
 169      *
 170      * @return the list of peer id's.
 171      */
 172     @Nonnull
 173     Collection<String> getPeerIds();
 174
 175     /**
 176      * Returns the PeerInfo for the given peer.
 177      *
 178      * @param peerId the id of the peer
 179      * @return the PeerInfo or null if not found
 180      */
 181     @Nullable
 182     PeerInfo getPeerInfo(String peerId);
 183
 184     /**
 185      * Adds a new peer.
 186      *
 187      * @param id the id of the new peer.
 188      * @param address the address of the new peer.
 189      * @param votingState the VotingState of the new peer.
 190      */
 191     void addToPeers(String id, String address, VotingState votingState);
 192
 193     /**
 194      * Removes a peer.
 195      *
 196      * @param id the id of the peer to remove.
 197      */
 198     void removePeer(String id);
 199
 200     /**
 201      * Returns an ActorSelection for a peer.
 202      *
 203      * @param peerId the id of the peer.
 204      * @return the actorSelection corresponding to the peer or null if the address has not yet been resolved.
 205      */
 206     @Nullable
 207     ActorSelection getPeerActorSelection(String peerId);
 208
 209     /**
 210      * Sets the address of a peer.
 211      *
 212      * @param peerId the id of the peer.
 213      * @param peerAddress the address of the peer.
 214      */
 215     void setPeerAddress(String peerId, String peerAddress);
 216
 217     /**
 218      * Returns the ConfigParams instance.
 219      *
 220      * @return the ConfigParams instance.
 221      */
 222     @Nonnull
 223     ConfigParams getConfigParams();
 224
 225     /**
 226      * Returns the SnapshotManager instance.
 227      *
 228      * @return the SnapshotManager instance.
 229      */
 230     @Nonnull
 231     SnapshotManager getSnapshotManager();
 232
 233     /**
 234      * Returns the DataPersistenceProvider instance.
 235      *
 236      * @return the DataPersistenceProvider instance.
 237      */
 238     @Nonnull
 239     DataPersistenceProvider getPersistenceProvider();
 240
 241     /**
 242      * Determines if there are any peer followers.
 243      *
 244      * @return true if there are followers otherwise false.
 245      */
 246     boolean hasFollowers();
 247
 248     /**
 249      * Returns the total available memory for use in calculations. Normally this returns JVM's max memory but can be
 250      * overridden for unit tests.
 251      *
 252      * @return the total memory.
 253      */
 254     long getTotalMemory();
 255
 256     /**
 257      * Sets the retriever of the total memory metric.
 258      *
 259      * @param retriever a supplier of the total memory metric.
 260      */
 261     @VisibleForTesting
 262     void setTotalMemoryRetriever(LongSupplier retriever);
 263
 264     /**
 265      * Returns the payload version to be used when replicating data.
 266      *
 267      * @return the payload version.
 268      */
 269     short getPayloadVersion();
 270
 271     /**
 272      * Returns the RaftPolicy used to determine certain Raft behaviors.
 273      *
 274      * @return the RaftPolicy instance.
 275      */
 276     @Nonnull
 277     RaftPolicy getRaftPolicy();
 278
 279     /**
 280      * Determines if there have been any dynamic server configuration changes applied.
 281      *
 282      * @return true if dynamic server configuration changes have been applied, false otherwise, meaning that static
 283      *         peer configuration is still in use.
 284      */
 285     boolean isDynamicServerConfigurationInUse();
 286
 287     /**
 288      * Sets that dynamic server configuration changes have been applied.
 289      */
 290     void setDynamicServerConfigurationInUse();
 291
 292     /**
 293      * Returns the peer information as a ServerConfigurationPayload if dynamic server configurations have been applied.
 294      *
 295      * @param includeSelf include this peer's info.
 296      * @return the peer information as a ServerConfigurationPayload or null if no dynamic server configurations have
 297      *         been applied.
 298      */
 299     @Nullable
 300     ServerConfigurationPayload getPeerServerInfo(boolean includeSelf);
 301
 302     /**
 303      * Determines if this peer is a voting member of the cluster.
 304      *
 305      * @return true if this peer is a voting member, false otherwise.
 306      */
 307     boolean isVotingMember();
 308
 309     /**
 310      * Determines if there are any voting peers.
 311      *
 312      * @return true if there are any voting peers, false otherwise.
 313      */
 314     boolean anyVotingPeers();
 315
 316     /**
 317      * Returns the current behavior attached to the RaftActor.
 318      *
 319      * @return current behavior.
 320      */
 321     RaftActorBehavior getCurrentBehavior();
 322
 323     /**
 324      * Returns the consumer of ApplyState operations. This is invoked by a behavior when a log entry needs to be
 325      * applied to the state.
 326      *
 327      * @return the Consumer
 328      */
 329     Consumer<ApplyState> getApplyStateConsumer();
 330
 331     /**
 332      * Creates a FileBackedOutputStream with a common configuration.
 333      *
 334      * @return a FileBackedOutputStream instance
 335      */
 336     @Nonnull
 337     FileBackedOutputStream newFileBackedOutputStream();
 338
 339     /**
 340      * Returns the RaftActorLeadershipTransferCohort if leadership transfer is in progress.
 341      *
 342      * @return the RaftActorLeadershipTransferCohort if leadership transfer is in progress, null otherwise
 343      */
 344     @Nullable
 345     RaftActorLeadershipTransferCohort getRaftActorLeadershipTransferCohort();
 346
 347     /**
 348      * Sets the RaftActorLeadershipTransferCohort for transferring leadership.
 349      *
 350      * @param leadershipTransferCohort the RaftActorLeadershipTransferCohort or null to clear the existing one
 351      */
 352     void setRaftActorLeadershipTransferCohort(@Nullable RaftActorLeadershipTransferCohort leadershipTransferCohort);
 353 }