Package org.opendaylight.controller.cluster.raft

Interface ReplicatedLog

All Known Implementing Classes:
AbstractReplicatedLog
@NonNullByDefault public interface ReplicatedLog
Represents the ReplicatedLog that needs to be kept in sync by the RaftActor.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    ReplicatedLog.StoredEntryMeta
    A combination of EntryMeta and indicator of whether the entry is stable.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    append(LogEntry entry)
    Appends an entry to the log if its index is already included in the log.
    boolean
    appendReceived(LogEntry entry, @Nullable Consumer<LogEntry> callback)
    Appends an entry received by a follower to the in-memory log and persists it as well, returning an indication whether or not a snapshot should be taken.
    boolean
    appendSubmitted(long index, long term, Payload command, Consumer<ReplicatedLogEntry> callback)
    Appends an entry submitted on the leader to the in-memory log and persists it as well.
    void
    captureSnapshotIfReady(EntryMeta lastEntry)
    Determines if a snapshot needs to be captured based on the count/memory consumed and initiates the capture.
    void
    clear()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use resetToSnapshot(Snapshot) instead.
    void
    clear(int startIndex, int endIndex)
    Clears the journal entries with startIndex (inclusive) and endIndex (exclusive).
    int
    dataSize()
    Returns the size of the data in the log (in bytes).
    LogEntry
    entryAt(long offset)
    Returns the entry and specified offset.
    long
    firstJournalIndex()
    Returns the journal index corresponding to the first entry in the journal.
    long
    getCommitIndex()
    Returns the index of highest log entry known to be committed.
    List<ReplicatedLogEntry>
    getFrom(long index)
    Returns a list of log entries starting from the given index to the end of the log.
    List<ReplicatedLogEntry>
    getFrom(long index, int maxEntries, long maxDataSize)
    Returns a list of log entries starting from the given index up to the given maximum of entries or the given maximum accumulated size, whichever comes first.
    long
    getLastApplied()
    Returns index of highest log entry applied to state machine.
    default long
    getLogEntryIndex(long index)
    Returns the actual index of the entry in replicated log for the given index or -1 if not found.
    default long
    getLogEntryOrSnapshotTerm(long index)
    Returns the actual term of the entry in the replicated log for the given index or, if not present, returns the snapshot term if the given index is in the snapshot or -1 otherwise.
    default long
    getLogEntryTerm(long index)
    Returns the actual term of the entry in the replicated log for the given index or -1 if not found.
    long
    getSnapshotIndex()
    Returns the index from which the snapshot was created, -1 otherwise.
    long
    getSnapshotTerm()
    Returns the term of the index from which the snapshot was created, -1 otherwise.
    void
    increaseJournalLogCapacity(int amount)
    Optimization method to increase the capacity of the journal log prior to appending entries.
    boolean
    isInSnapshot(long index)
    Checks if the entry is present in a snapshot.
    default boolean
    isLogEntryPresent(long index)
     
    boolean
    isPresent(long index)
    Checks if the entry at the specified index is present or not.
    @Nullable LogEntry
    last()
    Return the last replicated log entry in the log or null of not found.
    long
    lastAppliedJournalIndex()
    Returns the journalIndex corresponding to getLastApplied().
    default long
    lastIndex()
    Return the index of the last entry in the log or -1 if the log is empty.
    default @Nullable EntryMeta
    lastMeta()
    Return the last replicated log entry in the log or null of not found.
    default long
    lastTerm()
    Return the term of the last entry in the log or -1 if the log is empty.
    @Nullable LogEntry
    lookup(long index)
    Return the replicated log entry at the specified index.
    default @Nullable EntryMeta
    lookupMeta(long index)
    Return metadata about a replicated entry.
    @Nullable ReplicatedLog.StoredEntryMeta
    lookupStoredMeta(long index)
    Return ReplicatedLog.StoredEntryMeta a replicated entry.
    void
    markLastApplied()
    Mark the current value getLastApplied() for recovery purposes.
    SnapshotManager.CaptureSnapshot
    newCaptureSnapshot(@Nullable EntryMeta lastLogEntry, long replicatedToAllIndex, boolean mandatoryTrim, boolean hasFollowers)
    Constructs a SnapshotManager.CaptureSnapshot instance.
    void
    resetToLog(ReplicatedLog prev)
    Reset interal state to match specified ReplicatedLog.
    void
    resetToSnapshot(Snapshot snapshot)
    Reset internal state to specified Snapshot.
    void
    setCommitIndex(long commitIndex)
    Sets the index of highest log entry known to be committed.
    void
    setFirstJournalIndex(long newFirstJournalIndex)
    Sets the firstJournalIndex() value.
    void
    setLastApplied(long lastApplied)
    Sets index of highest log entry applied to state machine.
    void
    setSnapshotIndex(long snapshotIndex)
    Sets the snapshot index in the replicated log.
    void
    setSnapshotTerm(long snapshotTerm)
    Sets snapshot term.
    boolean
    shouldCaptureSnapshot(long logIndex)
    Determines if a snapshot should be captured based on the count/memory consumed.
    long
    size()
    Returns the number of entries in the journal.
    default void
    snapshotCommit()
    Sets the Replicated log to state after snapshot success.
    void
    snapshotCommit(boolean updateDataSize)
    Sets the Replicated log to state after snapshot success.
    void
    snapshotPreCommit(long snapshotCapturedIndex, long snapshotCapturedTerm)
    Handles all the bookkeeping in order to perform a rollback in the event of SaveSnapshotFailure.
    void
    snapshotRollback()
    Restores the replicated log to a state in the event of a save snapshot failure.
    boolean
    trimToReceive(long nextIndex)
    Removes entries all entries from the log starting at the given index, resetting lastIndex() to nextIndex - 1.

  • Method Details

    • entryAt

      LogEntry entryAt(long offset)
      Returns the entry and specified offset.
      Parameters:
      offset - the offset
      Returns:
      the LogEntry
      Throws:
      IndexOutOfBoundsException - if the offset is out of range (offset < 0 || offset >= size())

    • lookup

      @Nullable LogEntry lookup(long index)
      Return the replicated log entry at the specified index.
      Parameters:
      index - the index of the log entry
      Returns:
      the ReplicatedLogEntry if found, otherwise null if the adjusted index less than 0 or greater than the size of the in-memory journal

    • lookupMeta

      default @Nullable EntryMeta lookupMeta(long index)
      Return metadata about a replicated entry.
      Parameters:
      index - the index of the log entry
      Returns:
      the EntryMeta if found, otherwise null if the adjusted index less than 0 or greater than the size of the in-memory journal

    • lookupStoredMeta

      @Nullable ReplicatedLog.StoredEntryMeta lookupStoredMeta(long index)
      Return ReplicatedLog.StoredEntryMeta a replicated entry.
      Parameters:
      index - the index of the log entry
      Returns:
      the ReplicatedLog.StoredEntryMeta if found, otherwise null if the adjusted index less than 0 or greater than the size of the in-memory journal

    • last

      @Nullable LogEntry last()
      Return the last replicated log entry in the log or null of not found.
      Returns:
      the last replicated log entry in the log or null of not found.

    • lastMeta

      default @Nullable EntryMeta lastMeta()
      Return the last replicated log entry in the log or null of not found.
      Returns:
      the last replicated log entry in the log or null of not found.

    • lastIndex

      default long lastIndex()
      Return the index of the last entry in the log or -1 if the log is empty.
      Returns:
      the index of the last entry in the log or -1 if the log is empty.

    • lastTerm

      default long lastTerm()
      Return the term of the last entry in the log or -1 if the log is empty.
      Returns:
      the term of the last entry in the log or -1 if the log is empty.

    • getCommitIndex

      long getCommitIndex()
      Returns the index of highest log entry known to be committed.
      Returns:
      index of highest log entry known to be committed.

    • setCommitIndex

      void setCommitIndex(long commitIndex)
      Sets the index of highest log entry known to be committed.
      Parameters:
      commitIndex - new commit index

    • getLastApplied

      long getLastApplied()
      Returns index of highest log entry applied to state machine.
      Returns:
      index of highest log entry applied to state machine.

    • setLastApplied

      void setLastApplied(long lastApplied)
      Sets index of highest log entry applied to state machine.
      Parameters:
      lastApplied - the new applied index.

    • markLastApplied

      void markLastApplied()
      Mark the current value getLastApplied() for recovery purposes.

    • trimToReceive

      boolean trimToReceive(long nextIndex)
      Removes entries all entries from the log starting at the given index, resetting lastIndex() to nextIndex - 1.
      Parameters:
      nextIndex - the index of the first log entry to remove
      Returns:
      true if the operation succeeds

    • append

      boolean append(LogEntry entry)
      Appends an entry to the log if its index is already included in the log.
      Parameters:
      entry - the entry to append
      Returns:
      true if the entry was successfully appended, false otherwise.

    • increaseJournalLogCapacity

      void increaseJournalLogCapacity(int amount)
      Optimization method to increase the capacity of the journal log prior to appending entries.
      Parameters:
      amount - the amount to increase by

    • appendReceived

      boolean appendReceived(LogEntry entry, @Nullable Consumer<LogEntry> callback)
      Appends an entry received by a follower to the in-memory log and persists it as well, returning an indication whether or not a snapshot should be taken.
      Parameters:
      entry - the entry to append
      callback - optional callback to be notified when persistence is complete
      Returns:
      true if the journal requires trimming and a snapshot needs to be taken

    • appendSubmitted

      boolean appendSubmitted(long index, long term, Payload command, Consumer<ReplicatedLogEntry> callback)
      Appends an entry submitted on the leader to the in-memory log and persists it as well.
      Parameters:
      index - the index
      term - the term
      command - the command
      callback - the callback to be notified when persistence is complete
      Returns:
      true if the entry was successfully appended, false otherwise

    • getFrom

      List<ReplicatedLogEntry> getFrom(long index)
      Returns a list of log entries starting from the given index to the end of the log.
      Parameters:
      index - the index of the first log entry to get.
      Returns:
      the List of entries

    • getFrom

      List<ReplicatedLogEntry> getFrom(long index, int maxEntries, long maxDataSize)
      Returns a list of log entries starting from the given index up to the given maximum of entries or the given maximum accumulated size, whichever comes first.
      Parameters:
      index - the index of the first log entry to get
      maxEntries - the maximum number of entries to get
      maxDataSize - the maximum accumulated size of the log entries to get, negative means no limit
      Returns:
      the List of entries meeting the criteria.

    • size

      long size()
      Returns the number of entries in the journal.
      Returns:
      the number of entries

    • isPresent

      boolean isPresent(long index)
      Checks if the entry at the specified index is present or not.
      Parameters:
      index - the index of the log entry
      Returns:
      true if the entry is present in the in-memory journal

    • isInSnapshot

      boolean isInSnapshot(long index)
      Checks if the entry is present in a snapshot.
      Parameters:
      index - the index of the log entry
      Returns:
      true if the entry is in the snapshot. false if the entry is not in the snapshot even if the entry may be present in the replicated log

    • firstJournalIndex

      long firstJournalIndex()
      Returns the journal index corresponding to the first entry in the journal.
      Returns:
      the journal index corresponding to the first entry in the journal

    • setFirstJournalIndex

      void setFirstJournalIndex(long newFirstJournalIndex)
      Sets the firstJournalIndex() value.
      Parameters:
      newFirstJournalIndex - the new value of firstJournalIndex().

    • lastAppliedJournalIndex

      long lastAppliedJournalIndex()
      Returns the journalIndex corresponding to getLastApplied().
      Returns:
      the journalIndex corresponding to getLastApplied()

    • getSnapshotIndex

      long getSnapshotIndex()
      Returns the index from which the snapshot was created, -1 otherwise.
      Returns:
      the index from which the snapshot was created, -1 otherwise

    • getSnapshotTerm

      long getSnapshotTerm()
      Returns the term of the index from which the snapshot was created, -1 otherwise.
      Returns:
      the term of the index from which the snapshot was created, -1 otherwise

    • setSnapshotIndex

      void setSnapshotIndex(long snapshotIndex)
      Sets the snapshot index in the replicated log.
      Parameters:
      snapshotIndex - the index to set

    • setSnapshotTerm

      void setSnapshotTerm(long snapshotTerm)
      Sets snapshot term.
      Parameters:
      snapshotTerm - the term to set

    • getLogEntryIndex

      default long getLogEntryIndex(long index)
      Returns the actual index of the entry in replicated log for the given index or -1 if not found.
      Returns:
      the log entry index or -1 if not found

    • getLogEntryTerm

      default long getLogEntryTerm(long index)
      Returns the actual term of the entry in the replicated log for the given index or -1 if not found.
      Returns:
      the log entry term or -1 if not found

    • getLogEntryOrSnapshotTerm

      default long getLogEntryOrSnapshotTerm(long index)
      Returns the actual term of the entry in the replicated log for the given index or, if not present, returns the snapshot term if the given index is in the snapshot or -1 otherwise.
      Returns:
      the term or -1 otherwise

    • isLogEntryPresent

      default boolean isLogEntryPresent(long index)

    • clear

      @Deprecated(since="11.0.0", forRemoval=true) void clear()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use resetToSnapshot(Snapshot) instead.
      Clears all entries.

    • clear

      void clear(int startIndex, int endIndex)
      Clears the journal entries with startIndex (inclusive) and endIndex (exclusive).
      Parameters:
      startIndex - the start index (inclusive)
      endIndex - the end index (exclusive)

    • snapshotPreCommit

      void snapshotPreCommit(long snapshotCapturedIndex, long snapshotCapturedTerm)
      Handles all the bookkeeping in order to perform a rollback in the event of SaveSnapshotFailure.
      Parameters:
      snapshotCapturedIndex - the new snapshot index
      snapshotCapturedTerm - the new snapshot term

    • snapshotCommit

      default void snapshotCommit()
      Sets the Replicated log to state after snapshot success. This method is equivalent to snapshotCommit(true).

    • snapshotCommit

      void snapshotCommit(boolean updateDataSize)
      Sets the Replicated log to state after snapshot success. Most users will want to use snapshotCommit() instead.
      Parameters:
      updateDataSize - true if dataSize() should also be updated

    • snapshotRollback

      void snapshotRollback()
      Restores the replicated log to a state in the event of a save snapshot failure.

    • dataSize

      int dataSize()
      Returns the size of the data in the log (in bytes).
      Returns:
      the size of the data in the log (in bytes)

    • captureSnapshotIfReady

      void captureSnapshotIfReady(EntryMeta lastEntry)
      Determines if a snapshot needs to be captured based on the count/memory consumed and initiates the capture.
      Parameters:
      lastEntry - the last log entry.

    • shouldCaptureSnapshot

      boolean shouldCaptureSnapshot(long logIndex)
      Determines if a snapshot should be captured based on the count/memory consumed.
      Parameters:
      logIndex - the log index to use to determine if the log count has exceeded the threshold
      Returns:
      true if a snapshot should be captured, false otherwise

    • resetToLog

      void resetToLog(ReplicatedLog prev)
      Reset interal state to match specified ReplicatedLog.
      Parameters:
      prev - the log to reset to

    • resetToSnapshot

      void resetToSnapshot(Snapshot snapshot)
      Reset internal state to specified Snapshot.
      Parameters:
      snapshot - snapshot to reset to

    • newCaptureSnapshot

      SnapshotManager.CaptureSnapshot newCaptureSnapshot(@Nullable EntryMeta lastLogEntry, long replicatedToAllIndex, boolean mandatoryTrim, boolean hasFollowers)
      Constructs a SnapshotManager.CaptureSnapshot instance.
      Parameters:
      lastLogEntry - the last log entry for the snapshot.
      replicatedToAllIndex - the index of the last entry replicated to all followers.
      Returns:
      a new CaptureSnapshot instance.