Interface Log

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
FileBasedLog, InMemoryLog, LogCache
public interface Log extends Closeable
Durable storage for Raft consensus log entries, election metadata (term and vote), and state machine snapshots.

Implementations provide the persistence layer that backs the Raft consensus algorithm. Each Raft node owns exactly one Log instance for the lifetime of the node. The log stores three categories of data:

  • Entries: an ordered, 1-based sequence of LogEntry records appended during replication.
  • Election metadata: the current term (currentTerm(long)) and the candidate voted for in that term (votedFor(Address)). These values must survive restarts to preserve Raft's single-vote-per-term invariant.
  • Snapshot: a point-in-time capture of the state machine, used to compact the log.

Lifecycle

A Log instance must be initialized before any other method is called and closed when no longer needed. After close(), behavior of all other methods is undefined.

Durability and failure

Mutating operations declare IOException to signal storage failures. When an IOException is thrown, the operation did not complete and the log's state may be inconsistent. Callers must not assume partial progress unless a method's contract explicitly defines it (see append(long, LogEntries)).

When fsync is enabled, each mutating operation guarantees that data has reached stable storage before the call returns.

Thread safety

Implementations may assume single-writer semantics: at most one thread performs mutating operations at any given time. However, read-only accessors (currentTerm(), votedFor(), commitIndex(), firstAppended(), lastAppended()) must be safe to call concurrently from any thread while a mutating operation is in progress.

Delegation

Implementations that wrap another Log (e.g., caching or adapter layers) should delegate findCapability(Class) to the wrapped log so that the full delegation chain is discoverable.

Since:
0.1
Author:
Bela Ban
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    append(long index, LogEntries entries)
    Appends entries starting at the given index and advances lastAppended() accordingly.
    long
    commitIndex()
    Returns the current commit index.
    Log
    commitIndex(long new_index)
    Persists the commit index.
    long
    currentTerm()
    Returns the current Raft term.
    Log
    currentTerm(long new_term)
    Persists the current Raft term.
    void
    deleteAllEntriesStartingFrom(long start_index)
    Deletes all entries at and after start_index.
    default <T extends LogCapability>
    T
    findCapability(Class<T> capability)
    Looks up an optional capability provided by this log or any log in the delegation chain.
    long
    firstAppended()
    Returns the index of the first entry in the log.
    void
    forEach(ObjLongConsumer<LogEntry> function)
    Applies the function to every entry in the log.
    void
    forEach(ObjLongConsumer<LogEntry> function, long start_index, long end_index)
    Applies the function to each entry in the range [max(start_index, firstAppended) ..
    LogEntry
    get(long index)
    Returns the entry at the given index.
    ByteBuffer
    getSnapshot()
    Returns the most recently stored snapshot.
    void
    init(String log_name, Map<String,String> args)
    Initializes this log with the given identity and optional configuration.
    long
    lastAppended()
    Returns the index of the last appended entry.
    int
    readSnapshotRegion(long offset, byte[] dst, int dstOffset, int length)
    Reads up to length bytes from the snapshot data starting at offset.
    void
    reinitializeTo(long index, LogEntry entry)
    Resets the log to contain only the given entry at the given index.
    void
    setSnapshot(InputStream input)
    Stores a snapshot of the state machine, replacing any previously stored snapshot.
    void
    setSnapshot(ByteBuffer sn)
    Stores a snapshot of the state machine, replacing any previously stored snapshot.
    default long
    size()
    Returns the number of entries in the log.
    long
    sizeInBytes()
    Returns the approximate size of the log data in bytes.
    long
    snapshotSize()
    Returns the size of the snapshot.
    void
    truncate(long index_exclusive)
    Removes all entries before the given index.
    boolean
    useFsync()
    Returns whether writes are forced to stable storage before mutating operations return.
    Log
    useFsync(boolean f)
    Controls whether mutating operations force data to stable storage (fsync) before returning.
    org.jgroups.Address
    votedFor()
    Returns the candidate this node voted for in the current term.
    Log
    votedFor(org.jgroups.Address member)
    Persists the vote for the given candidate in the current term.

    Methods inherited from interface Closeable

    close

  • Method Details

    • init

      void init(String log_name, Map<String,String> args) throws Exception
      Initializes this log with the given identity and optional configuration. Must be called exactly once before any other method.
      Parameters:
      log_name - a name used to derive the storage identity (file name, database table, etc.). Two logs initialized with the same name in the same environment share state.
      args - implementation-specific configuration parameters, may be null
      Throws:
      Exception - if initialization fails (missing directory, permission denied, corrupt storage, etc.)

    • useFsync

      Log useFsync(boolean f)
      Controls whether mutating operations force data to stable storage (fsync) before returning.
      Parameters:
      f - true to force all writes to stable storage
      Returns:
      this log

    • useFsync

      boolean useFsync()
      Returns whether writes are forced to stable storage before mutating operations return.
      Returns:
      true if fsync is enabled

    • currentTerm

      long currentTerm()
      Returns the current Raft term.
      Returns:
      the current term, or 0 if not yet set

    • currentTerm

      Log currentTerm(long new_term) throws IOException
      Persists the current Raft term. The Raft protocol guarantees that terms are monotonically increasing.
      Parameters:
      new_term - the term to persist
      Returns:
      this log
      Throws:
      IOException - if the term cannot be persisted

    • votedFor

      org.jgroups.Address votedFor()
      Returns the candidate this node voted for in the current term.
      Returns:
      the address of the voted-for candidate, or null if no vote has been cast in this term

    • votedFor

      Log votedFor(org.jgroups.Address member) throws IOException
      Persists the vote for the given candidate in the current term. The Raft protocol guarantees at most one vote per term. Passing null clears the vote, typically at term boundaries.
      Parameters:
      member - the candidate address, or null to clear the vote
      Returns:
      this log
      Throws:
      IOException - if the vote cannot be persisted

    • commitIndex

      long commitIndex()
      Returns the current commit index.
      Returns:
      the commit index, or 0 if no entries have been committed

    • commitIndex

      Log commitIndex(long new_index) throws IOException
      Persists the commit index.
      Parameters:
      new_index - the new commit index
      Returns:
      this log
      Throws:
      IOException - if the commit index cannot be persisted

    • firstAppended

      long firstAppended()
      Returns the index of the first entry in the log.
      Returns:
      the first entry index, or 0 if the log is empty

    • lastAppended

      long lastAppended()
      Returns the index of the last appended entry.
      Returns:
      the last appended index, or 0 if the log is empty

    • setSnapshot

      void setSnapshot(ByteBuffer sn) throws IOException
      Stores a snapshot of the state machine, replacing any previously stored snapshot.
      Parameters:
      sn - the snapshot data
      Throws:
      IOException - if the snapshot cannot be stored

    • setSnapshot

      void setSnapshot(InputStream input) throws IOException
      Stores a snapshot of the state machine, replacing any previously stored snapshot.
      Parameters:
      input - an input stream to read the snapshot data from
      Throws:
      IOException - if the snapshot cannot be stored

    • getSnapshot

      ByteBuffer getSnapshot() throws IOException
      Returns the most recently stored snapshot.
      Returns:
      the snapshot data, or null if no snapshot has been stored
      Throws:
      IOException - if the snapshot cannot be read

    • snapshotSize

      long snapshotSize() throws IOException
      Returns the size of the snapshot.
      Returns:
      returns the size of the stored snapshot.
      Throws:
      IOException - if not possible to extract the snapshot size

    • readSnapshotRegion

      int readSnapshotRegion(long offset, byte[] dst, int dstOffset, int length) throws IOException
      Reads up to length bytes from the snapshot data starting at offset.
      Parameters:
      offset - offset to start reading from
      dst - buffer to store the read bytes
      dstOffset - offset to start writing the bytes at the destination buffer
      length - how many bytes to try to read
      Returns:
      the number of actual read bytes
      Throws:
      IOException - if not possible to read the snapshot

    • append

      long append(long index, LogEntries entries) throws IOException
      Appends entries starting at the given index and advances lastAppended() accordingly.

      On partial failure, lastAppended must reflect the last successfully written entry rather than reverting to the value before the call. For example, if lastAppended was 1 and 100 entries were submitted but the operation failed at entry 51, lastAppended must be 50 after the exception.

      Parameters:
      index - the index at which to begin appending
      entries - the entries to append
      Returns:
      the index of the last appended entry
      Throws:
      IOException - if one or more entries cannot be written to storage

    • get

      LogEntry get(long index) throws IOException
      Returns the entry at the given index.
      Parameters:
      index - the log index to retrieve
      Returns:
      the entry, or null if no entry exists at that index
      Throws:
      IOException - if the entry cannot be read from storage

    • truncate

      void truncate(long index_exclusive) throws IOException
      Removes all entries before the given index. After this call, firstAppended() equals index_exclusive.

      If index_exclusive exceeds commitIndex(), the commit index is used instead to prevent truncating committed entries.

      Parameters:
      index_exclusive - entries strictly before this index are removed
      Throws:
      IOException - if the truncation cannot be completed

    • reinitializeTo

      void reinitializeTo(long index, LogEntry entry) throws IOException
      Resets the log to contain only the given entry at the given index. Sets firstAppended(), lastAppended(), and commitIndex() to index. The next entry will be appended at index + 1.

      Typically called after installing a snapshot received from the leader.

      Parameters:
      index - the new starting index
      entry - the single entry to store
      Throws:
      IOException - if the log cannot be reinitialized

    • deleteAllEntriesStartingFrom

      void deleteAllEntriesStartingFrom(long start_index) throws IOException
      Deletes all entries at and after start_index. Updates lastAppended() and currentTerm() to reflect the remaining log.
      Parameters:
      start_index - the first index to delete (inclusive)
      Throws:
      IOException - if the deletion cannot be completed

    • forEach

      void forEach(ObjLongConsumer<LogEntry> function, long start_index, long end_index) throws IOException
      Applies the function to each entry in the range [max(start_index, firstAppended) .. min(end_index, lastAppended)], inclusive.
      Parameters:
      function - invoked with each entry and its index
      start_index - the start of the range (inclusive), clamped to firstAppended()
      end_index - the end of the range (inclusive), clamped to lastAppended()
      Throws:
      IOException - if an entry cannot be read

    • forEach

      void forEach(ObjLongConsumer<LogEntry> function) throws IOException
      Applies the function to every entry in the log. Equivalent to forEach(function, firstAppended(), lastAppended()).
      Parameters:
      function - invoked with each entry and its index
      Throws:
      IOException - if an entry cannot be read

    • size

      default long size()
      Returns the number of entries in the log.
      Returns:
      the entry count

    • sizeInBytes

      long sizeInBytes()
      Returns the approximate size of the log data in bytes.
      Returns:
      the size in bytes

    • findCapability

      default <T extends LogCapability> T findCapability(Class<T> capability)
      Looks up an optional capability provided by this log or any log in the delegation chain.

      Implementations that wrap another Log should delegate to the wrapped log when they do not provide the requested capability themselves.

      Type Parameters:
      T - the capability type
      Parameters:
      capability - the capability interface to look up
      Returns:
      the capability instance, or null if not available