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.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;
  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      * Return an Executor which is guaranteed to run tasks in the context of {@link #getActor()}.
  70      *
  71      * @return An executor.
  72      */
  73     @NonNull Executor getExecutor();
  74
  75     /**
  76      * The akka Cluster singleton for the actor system if one is configured.
  77      *
  78      * @return an Optional containing the Cluster instance is present.
  79      */
  80     Optional<Cluster> getCluster();
  81
  82     /**
  83      * Returns the current ElectionTerm information.
  84      *
  85      * @return the ElectionTerm.
  86      */
  87     @NonNull ElectionTerm getTermInformation();
  88
  89     /**
  90      * Returns the index of highest log entry known to be committed.
  91      *
  92      * @return index of highest log entry known to be committed.
  93      */
  94     long getCommitIndex();
  95
  96
  97     /**
  98      * Sets the index of highest log entry known to be committed.
  99      *
 100      * @param commitIndex new commit index
 101      */
 102     void setCommitIndex(long commitIndex);
 103
 104     /**
 105      * Returns index of highest log entry applied to state machine.
 106      *
 107      * @return index of highest log entry applied to state machine.
 108      */
 109     long getLastApplied();
 110
 111     /**
 112      * Sets index of highest log entry applied to state machine.
 113      *
 114      * @param lastApplied the new applied index.
 115      */
 116     void setLastApplied(long lastApplied);
 117
 118     /**
 119      * Sets the ReplicatedLog instance.
 120      *
 121      * @param replicatedLog the ReplicatedLog instance.
 122      */
 123     void setReplicatedLog(@NonNull ReplicatedLog replicatedLog);
 124
 125     /**
 126      * Returns the ReplicatedLog instance.
 127      *
 128      * @return the ReplicatedLog instance.
 129      */
 130     @NonNull ReplicatedLog getReplicatedLog();
 131
 132     /**
 133      * Returns the The ActorSystem associated with this context.
 134      *
 135      * @return the ActorSystem.
 136      */
 137     @NonNull ActorSystem getActorSystem();
 138
 139     /**
 140      * Returns the logger to be used for logging messages.
 141      *
 142      * @return the logger.
 143      */
 144     @NonNull Logger getLogger();
 145
 146     /**
 147      * Gets the address of a peer as a String. This is the same format in which a consumer would provide the address.
 148      *
 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.
 151      */
 152     @Nullable String getPeerAddress(String peerId);
 153
 154     /**
 155      * Updates the peers and information to match the given ServerConfigurationPayload.
 156      *
 157      * @param serverCfgPayload the ServerConfigurationPayload.
 158      */
 159     void updatePeerIds(ServerConfigurationPayload serverCfgPayload);
 160
 161     /**
 162      * Returns the PeerInfo instances for each peer.
 163      *
 164      * @return list of PeerInfo
 165      */
 166     @NonNull Collection<PeerInfo> getPeers();
 167
 168     /**
 169      * Returns the id's for each peer.
 170      *
 171      * @return the list of peer id's.
 172      */
 173     @NonNull 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 PeerInfo getPeerInfo(String peerId);
 182
 183     /**
 184      * Adds a new peer.
 185      *
 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.
 189      */
 190     void addToPeers(String id, String address, VotingState votingState);
 191
 192     /**
 193      * Removes a peer.
 194      *
 195      * @param id the id of the peer to remove.
 196      */
 197     void removePeer(String id);
 198
 199     /**
 200      * Returns an ActorSelection for a peer.
 201      *
 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.
 204      */
 205     @Nullable ActorSelection getPeerActorSelection(String peerId);
 206
 207     /**
 208      * Sets the address of a peer.
 209      *
 210      * @param peerId the id of the peer.
 211      * @param peerAddress the address of the peer.
 212      */
 213     void setPeerAddress(String peerId, String peerAddress);
 214
 215     /**
 216      * Returns the ConfigParams instance.
 217      *
 218      * @return the ConfigParams instance.
 219      */
 220     @NonNull ConfigParams getConfigParams();
 221
 222     /**
 223      * Returns the SnapshotManager instance.
 224      *
 225      * @return the SnapshotManager instance.
 226      */
 227     @NonNull SnapshotManager getSnapshotManager();
 228
 229     /**
 230      * Returns the DataPersistenceProvider instance.
 231      *
 232      * @return the DataPersistenceProvider instance.
 233      */
 234     @NonNull DataPersistenceProvider getPersistenceProvider();
 235
 236     /**
 237      * Determines if there are any peer followers.
 238      *
 239      * @return true if there are followers otherwise false.
 240      */
 241     boolean hasFollowers();
 242
 243     /**
 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.
 246      *
 247      * @return the total memory.
 248      */
 249     long getTotalMemory();
 250
 251     /**
 252      * Sets the retriever of the total memory metric.
 253      *
 254      * @param retriever a supplier of the total memory metric.
 255      */
 256     @VisibleForTesting
 257     void setTotalMemoryRetriever(LongSupplier retriever);
 258
 259     /**
 260      * Returns the payload version to be used when replicating data.
 261      *
 262      * @return the payload version.
 263      */
 264     short getPayloadVersion();
 265
 266     /**
 267      * Returns the RaftPolicy used to determine certain Raft behaviors.
 268      *
 269      * @return the RaftPolicy instance.
 270      */
 271     @NonNull RaftPolicy getRaftPolicy();
 272
 273     /**
 274      * Determines if there have been any dynamic server configuration changes applied.
 275      *
 276      * @return true if dynamic server configuration changes have been applied, false otherwise, meaning that static
 277      *         peer configuration is still in use.
 278      */
 279     boolean isDynamicServerConfigurationInUse();
 280
 281     /**
 282      * Sets that dynamic server configuration changes have been applied.
 283      */
 284     void setDynamicServerConfigurationInUse();
 285
 286     /**
 287      * Returns the peer information as a ServerConfigurationPayload if dynamic server configurations have been applied.
 288      *
 289      * @param includeSelf include this peer's info.
 290      * @return the peer information as a ServerConfigurationPayload or null if no dynamic server configurations have
 291      *         been applied.
 292      */
 293     @Nullable ServerConfigurationPayload getPeerServerInfo(boolean includeSelf);
 294
 295     /**
 296      * Determines if this peer is a voting member of the cluster.
 297      *
 298      * @return true if this peer is a voting member, false otherwise.
 299      */
 300     boolean isVotingMember();
 301
 302     /**
 303      * Determines if there are any voting peers.
 304      *
 305      * @return true if there are any voting peers, false otherwise.
 306      */
 307     boolean anyVotingPeers();
 308
 309     /**
 310      * Returns the current behavior attached to the RaftActor.
 311      *
 312      * @return current behavior.
 313      */
 314     RaftActorBehavior getCurrentBehavior();
 315
 316     /**
 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.
 319      *
 320      * @return the Consumer
 321      */
 322     Consumer<ApplyState> getApplyStateConsumer();
 323
 324     /**
 325      * Returns the {@link FileBackedOutputStreamFactory} instance with a common configuration.
 326      *
 327      * @return the {@link FileBackedOutputStreamFactory};
 328      */
 329     @NonNull FileBackedOutputStreamFactory getFileBackedOutputStreamFactory();
 330
 331     /**
 332      * Returns the RaftActorLeadershipTransferCohort if leadership transfer is in progress.
 333      *
 334      * @return the RaftActorLeadershipTransferCohort if leadership transfer is in progress, null otherwise
 335      */
 336     @Nullable RaftActorLeadershipTransferCohort getRaftActorLeadershipTransferCohort();
 337
 338     /**
 339      * Sets the RaftActorLeadershipTransferCohort for transferring leadership.
 340      *
 341      * @param leadershipTransferCohort the RaftActorLeadershipTransferCohort or null to clear the existing one
 342      */
 343     void setRaftActorLeadershipTransferCohort(@Nullable RaftActorLeadershipTransferCohort leadershipTransferCohort);
 344 }