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 ReplicatedLogEntry get(long index);
  30
  31     /**
  32      * Return the last replicated log entry in the log or null of not found.
  33      */
  34     @Nullable ReplicatedLogEntry last();
  35
  36     /**
  37      * Return the index of the last entry in the log or -1 if the log is empty.
  38      */
  39     long lastIndex();
  40
  41     /**
  42      * Return the term of the last entry in the log or -1 if the log is empty.
  43      */
  44     long lastTerm();
  45
  46     /**
  47      * Removes entries from the in-memory log starting at the given index.
  48      *
  49      * @param index the index of the first log entry to remove
  50      * @return the adjusted index of the first log entry removed or -1 if the log entry is not found.
  51      */
  52     long removeFrom(long index);
  53
  54     /**
  55      * Removes entries from the in-memory log a nd the persisted log starting at the given index.
  56      * <p>
  57      * The persisted information would then be used during recovery to properly
  58      * reconstruct the state of the in-memory replicated log
  59      *
  60      * @param index the index of the first log entry to remove
  61      * @return
  62      */
  63     boolean removeFromAndPersist(long index);
  64
  65     /**
  66      * Appends an entry to the log.
  67      *
  68      * @param replicatedLogEntry the entry to append
  69      * @return true if the entry was successfully appended, false otherwise. An entry can fail to append if
  70      *         the index is already included in the log.
  71      */
  72     boolean append(ReplicatedLogEntry replicatedLogEntry);
  73
  74     /**
  75      * Optimization method to increase the capacity of the journal log prior to appending entries.
  76      *
  77      * @param amount the amount to increase by
  78      */
  79     void increaseJournalLogCapacity(int amount);
  80
  81     /**
  82      * Appends an entry to the in-memory log and persists it as well.
  83      *
  84      * @param replicatedLogEntry the entry to append
  85      */
  86     void appendAndPersist(final ReplicatedLogEntry replicatedLogEntry);
  87
  88     void appendAndPersist(ReplicatedLogEntry replicatedLogEntry, Procedure<ReplicatedLogEntry> callback);
  89
  90     /**
  91      * Returns a list of log entries starting from the given index to the end of the log.
  92      *
  93      * @param index the index of the first log entry to get.
  94      * @return the List of entries
  95      */
  96     @Nonnull List<ReplicatedLogEntry> getFrom(long index);
  97
  98     /**
  99      * Returns a list of log entries starting from the given index up to the given maximum of entries or
 100      * the given maximum accumulated size, whichever comes first.
 101      *
 102      * @param index the index of the first log entry to get
 103      * @param maxEntries the maximum number of entries to get
 104      * @param maxDataSize the maximum accumulated size of the log entries to get
 105      * @return the List of entries meeting the criteria.
 106      */
 107     @Nonnull List<ReplicatedLogEntry> getFrom(long index, int maxEntries, long maxDataSize);
 108
 109     /**
 110      *
 111      * @return the number of entries in the journal
 112      */
 113     long size();
 114
 115     /**
 116      * Checks if the entry at the specified index is present or not
 117      *
 118      * @param index the index of the log entry
 119      * @return true if the entry is present in the in-memory journal
 120      */
 121     boolean isPresent(long index);
 122
 123     /**
 124      * Checks if the entry is present in a snapshot
 125      *
 126      * @param index the index of the log entry
 127      * @return true if the entry is in the snapshot. false if the entry is not
 128      * in the snapshot even if the entry may be present in the replicated log
 129      */
 130     boolean isInSnapshot(long index);
 131
 132     /**
 133      * Get the index of the snapshot
 134      *
 135      * @return the index from which the snapshot was created. -1 otherwise.
 136      */
 137     long getSnapshotIndex();
 138
 139     /**
 140      * Get the term of the snapshot
 141      *
 142      * @return the term of the index from which the snapshot was created. -1
 143      * otherwise
 144      */
 145     long getSnapshotTerm();
 146
 147     /**
 148      * sets the snapshot index in the replicated log
 149      * @param snapshotIndex
 150      */
 151     void setSnapshotIndex(long snapshotIndex);
 152
 153     /**
 154      * sets snapshot term
 155      * @param snapshotTerm
 156      */
 157     void setSnapshotTerm(long snapshotTerm);
 158
 159     /**
 160      * Clears the journal entries with startIndex(inclusive) and endIndex (exclusive)
 161      * @param startIndex
 162      * @param endIndex
 163      */
 164     void clear(int startIndex, int endIndex);
 165
 166     /**
 167      * Handles all the bookkeeping in order to perform a rollback in the
 168      * event of SaveSnapshotFailure
 169      * @param snapshotCapturedIndex
 170      * @param snapshotCapturedTerm
 171      */
 172     void snapshotPreCommit(long snapshotCapturedIndex, long snapshotCapturedTerm);
 173
 174     /**
 175      * Sets the Replicated log to state after snapshot success.
 176      */
 177     void snapshotCommit();
 178
 179     /**
 180      * Restores the replicated log to a state in the event of a save snapshot failure
 181      */
 182     void snapshotRollback();
 183
 184     /**
 185      * Size of the data in the log (in bytes)
 186      */
 187     int dataSize();
 188
 189     /**
 190      * We decide if snapshot need to be captured based on the count/memory consumed.
 191      * @param replicatedLogEntry
 192      */
 193     void captureSnapshotIfReady(ReplicatedLogEntry replicatedLogEntry);
 194
 195 }