opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLog.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.japi.Procedure;
  12 import java.util.List;
  13 import javax.annotation.Nonnull;
  14 import javax.annotation.Nullable;
  15
  16 /**
  17  * Represents the ReplicatedLog that needs to be kept in sync by the RaftActor.
  18  */
  19 public interface ReplicatedLog {
  20     long NO_MAX_SIZE = -1;
  21
  22     /**
  23      * Return the replicated log entry at the specified index.
  24      *
  25      * @param index the index of the log entry
  26      * @return the ReplicatedLogEntry if found, otherwise null if the adjusted index less than 0 or
  27      *         greater than the size of the in-memory journal
  28      */
  29     @Nullable
  30     ReplicatedLogEntry get(long index);
  31
  32     /**
  33      * Return the last replicated log entry in the log or null of not found.
  34      *
  35      * @return the last replicated log entry in the log or null of not found.
  36      */
  37     @Nullable
  38     ReplicatedLogEntry last();
  39
  40     /**
  41      * Return the index of the last entry in the log or -1 if the log is empty.
  42      *
  43      * @return the index of the last entry in the log or -1 if the log is empty.
  44      */
  45     long lastIndex();
  46
  47     /**
  48      * Return the term of the last entry in the log or -1 if the log is empty.
  49      *
  50      * @return the term of the last entry in the log or -1 if the log is empty.
  51      */
  52     long lastTerm();
  53
  54     /**
  55      * Removes entries from the in-memory log starting at the given index.
  56      *
  57      * @param index the index of the first log entry to remove
  58      * @return the adjusted index of the first log entry removed or -1 if the log entry is not found.
  59      */
  60     long removeFrom(long index);
  61
  62     /**
  63      * Removes entries from the in-memory log and the persisted log starting at the given index.
  64      *
  65      * <p>
  66      * The persisted information would then be used during recovery to properly
  67      * reconstruct the state of the in-memory replicated log
  68      *
  69      * @param index the index of the first log entry to remove
  70      * @return true if entries were removed, false otherwise
  71      */
  72     boolean removeFromAndPersist(long index);
  73
  74     /**
  75      * Appends an entry to the log.
  76      *
  77      * @param replicatedLogEntry the entry to append
  78      * @return true if the entry was successfully appended, false otherwise. An entry can fail to append if
  79      *         the index is already included in the log.
  80      */
  81     boolean append(ReplicatedLogEntry replicatedLogEntry);
  82
  83     /**
  84      * Optimization method to increase the capacity of the journal log prior to appending entries.
  85      *
  86      * @param amount the amount to increase by
  87      */
  88     void increaseJournalLogCapacity(int amount);
  89
  90     /**
  91      * Appends an entry to the in-memory log and persists it as well.
  92      *
  93      * @param replicatedLogEntry the entry to append
  94      * @param callback the Procedure to be notified when persistence is complete (optional).
  95      * @param doAsync if true, the persistent actor can receive subsequent messages to process in between the persist
  96      *        call and the execution of the associated callback. If false, subsequent messages are stashed and get
  97      *        delivered after persistence is complete and the associated callback is executed.
  98      * @return true if the entry was successfully appended, false otherwise.
  99      */
 100     boolean appendAndPersist(@Nonnull ReplicatedLogEntry replicatedLogEntry,
 101             @Nullable Procedure<ReplicatedLogEntry> callback, boolean doAsync);
 102
 103     /**
 104      * Returns a list of log entries starting from the given index to the end of the log.
 105      *
 106      * @param index the index of the first log entry to get.
 107      * @return the List of entries
 108      */
 109     @Nonnull List<ReplicatedLogEntry> getFrom(long index);
 110
 111     /**
 112      * Returns a list of log entries starting from the given index up to the given maximum of entries or
 113      * the given maximum accumulated size, whichever comes first.
 114      *
 115      * @param index the index of the first log entry to get
 116      * @param maxEntries the maximum number of entries to get
 117      * @param maxDataSize the maximum accumulated size of the log entries to get
 118      * @return the List of entries meeting the criteria.
 119      */
 120     @Nonnull List<ReplicatedLogEntry> getFrom(long index, int maxEntries, long maxDataSize);
 121
 122     /**
 123      * Returns the number of entries in the journal.
 124      *
 125      * @return the number of entries
 126      */
 127     long size();
 128
 129     /**
 130      * Checks if the entry at the specified index is present or not.
 131      *
 132      * @param index the index of the log entry
 133      * @return true if the entry is present in the in-memory journal
 134      */
 135     boolean isPresent(long index);
 136
 137     /**
 138      * Checks if the entry is present in a snapshot.
 139      *
 140      * @param index the index of the log entry
 141      * @return true if the entry is in the snapshot. false if the entry is not in the snapshot even if the entry may
 142      *         be present in the replicated log
 143      */
 144     boolean isInSnapshot(long index);
 145
 146     /**
 147      * Returns the index of the snapshot.
 148      *
 149      * @return the index from which the snapshot was created. -1 otherwise.
 150      */
 151     long getSnapshotIndex();
 152
 153     /**
 154      * Returns the term of the snapshot.
 155      *
 156      * @return the term of the index from which the snapshot was created. -1 otherwise
 157      */
 158     long getSnapshotTerm();
 159
 160     /**
 161      * Sets the snapshot index in the replicated log.
 162      *
 163      * @param snapshotIndex the index to set
 164      */
 165     void setSnapshotIndex(long snapshotIndex);
 166
 167     /**
 168      * Sets snapshot term.
 169      *
 170      * @param snapshotTerm the term to set
 171      */
 172     void setSnapshotTerm(long snapshotTerm);
 173
 174     /**
 175      * Clears the journal entries with startIndex (inclusive) and endIndex (exclusive).
 176      *
 177      * @param startIndex the start index (inclusive)
 178      * @param endIndex the end index (exclusive)
 179      */
 180     void clear(int startIndex, int endIndex);
 181
 182     /**
 183      * Handles all the bookkeeping in order to perform a rollback in the event of SaveSnapshotFailure.
 184      *
 185      * @param snapshotCapturedIndex the new snapshot index
 186      * @param snapshotCapturedTerm the new snapshot term
 187      */
 188     void snapshotPreCommit(long snapshotCapturedIndex, long snapshotCapturedTerm);
 189
 190     /**
 191      * Sets the Replicated log to state after snapshot success.
 192      */
 193     void snapshotCommit();
 194
 195     /**
 196      * Restores the replicated log to a state in the event of a save snapshot failure.
 197      */
 198     void snapshotRollback();
 199
 200     /**
 201      * Returns the size of the data in the log (in bytes).
 202      *
 203      * @return the size of the data in the log (in bytes)
 204      */
 205     int dataSize();
 206
 207     /**
 208      * Determines if a snapshot needs to be captured based on the count/memory consumed and initiates the capture.
 209      *
 210      * @param replicatedLogEntry the last log entry.
 211      */
 212     void captureSnapshotIfReady(ReplicatedLogEntry replicatedLogEntry);
 213
 214     /**
 215      * Determines if a snapshot should be captured based on the count/memory consumed.
 216      *
 217      * @param logIndex the log index to use to determine if the log count has exceeded the threshold
 218      * @return true if a snapshot should be captured, false otherwise
 219      */
 220     boolean shouldCaptureSnapshot(long logIndex);
 221 }