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