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