Class FileBasedLog

java.lang.Object
org.jgroups.protocols.raft.FileBasedLog
All Implemented Interfaces:
Closeable, AutoCloseable, Log
public class FileBasedLog extends Object implements Log
A Log implementation stored in a file.
Since:
0.5.4
Author:
Pedro Ruivo

  • Constructor Summary

    Constructors
    Constructor
    Description
    FileBasedLog()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    append(long index, LogEntries entries)
    Appends entries starting at the given index and advances Log.lastAppended() accordingly.
    void
    close()
     
    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.
    <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.
    long
    sizeInBytes()
    Returns the approximate size of the log data in bytes.
    long
    snapshotSize()
    Returns the size of the snapshot.
    String
    toString()
     
    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 value)
    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 class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface Log

    size

  • Constructor Details

    • FileBasedLog

      public FileBasedLog()

  • Method Details

    • init

      public void init(String log_name, Map<String,String> args) throws Exception
      Description copied from interface: Log
      Initializes this log with the given identity and optional configuration. Must be called exactly once before any other method.
      Specified by:
      init in interface Log
      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

      public Log useFsync(boolean value)
      Description copied from interface: Log
      Controls whether mutating operations force data to stable storage (fsync) before returning.
      Specified by:
      useFsync in interface Log
      Parameters:
      value - true to force all writes to stable storage
      Returns:
      this log

    • useFsync

      public boolean useFsync()
      Description copied from interface: Log
      Returns whether writes are forced to stable storage before mutating operations return.
      Specified by:
      useFsync in interface Log
      Returns:
      true if fsync is enabled

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • currentTerm

      public long currentTerm()
      Description copied from interface: Log
      Returns the current Raft term.
      Specified by:
      currentTerm in interface Log
      Returns:
      the current term, or 0 if not yet set

    • currentTerm

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

    • votedFor

      public org.jgroups.Address votedFor()
      Description copied from interface: Log
      Returns the candidate this node voted for in the current term.
      Specified by:
      votedFor in interface Log
      Returns:
      the address of the voted-for candidate, or null if no vote has been cast in this term

    • votedFor

      public Log votedFor(org.jgroups.Address member) throws IOException
      Description copied from interface: Log
      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.
      Specified by:
      votedFor in interface Log
      Parameters:
      member - the candidate address, or null to clear the vote
      Returns:
      this log
      Throws:
      IOException - if the vote cannot be persisted

    • commitIndex

      public long commitIndex()
      Description copied from interface: Log
      Returns the current commit index.
      Specified by:
      commitIndex in interface Log
      Returns:
      the commit index, or 0 if no entries have been committed

    • commitIndex

      public Log commitIndex(long new_index) throws IOException
      Description copied from interface: Log
      Persists the commit index.
      Specified by:
      commitIndex in interface Log
      Parameters:
      new_index - the new commit index
      Returns:
      this log
      Throws:
      IOException - if the commit index cannot be persisted

    • firstAppended

      public long firstAppended()
      Description copied from interface: Log
      Returns the index of the first entry in the log.
      Specified by:
      firstAppended in interface Log
      Returns:
      the first entry index, or 0 if the log is empty

    • lastAppended

      public long lastAppended()
      Description copied from interface: Log
      Returns the index of the last appended entry.
      Specified by:
      lastAppended in interface Log
      Returns:
      the last appended index, or 0 if the log is empty

    • setSnapshot

      public void setSnapshot(ByteBuffer sn) throws IOException
      Description copied from interface: Log
      Stores a snapshot of the state machine, replacing any previously stored snapshot.
      Specified by:
      setSnapshot in interface Log
      Parameters:
      sn - the snapshot data
      Throws:
      IOException - if the snapshot cannot be stored

    • setSnapshot

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

    • getSnapshot

      public ByteBuffer getSnapshot() throws IOException
      Description copied from interface: Log
      Returns the most recently stored snapshot.
      Specified by:
      getSnapshot in interface Log
      Returns:
      the snapshot data, or null if no snapshot has been stored
      Throws:
      IOException - if the snapshot cannot be read

    • snapshotSize

      public long snapshotSize() throws IOException
      Description copied from interface: Log
      Returns the size of the snapshot.
      Specified by:
      snapshotSize in interface Log
      Returns:
      returns the size of the stored snapshot.
      Throws:
      IOException - if not possible to extract the snapshot size

    • readSnapshotRegion

      public int readSnapshotRegion(long offset, byte[] dst, int dstOffset, int length) throws IOException
      Description copied from interface: Log
      Reads up to length bytes from the snapshot data starting at offset.
      Specified by:
      readSnapshotRegion in interface Log
      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

      public long append(long index, LogEntries entries) throws IOException
      Description copied from interface: Log
      Appends entries starting at the given index and advances Log.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.

      Specified by:
      append in interface Log
      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

      public LogEntry get(long index) throws IOException
      Description copied from interface: Log
      Returns the entry at the given index.
      Specified by:
      get in interface Log
      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

      public void truncate(long index_exclusive) throws IOException
      Description copied from interface: Log
      Removes all entries before the given index. After this call, Log.firstAppended() equals index_exclusive.

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

      Specified by:
      truncate in interface Log
      Parameters:
      index_exclusive - entries strictly before this index are removed
      Throws:
      IOException - if the truncation cannot be completed

    • reinitializeTo

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

      Typically called after installing a snapshot received from the leader.

      Specified by:
      reinitializeTo in interface Log
      Parameters:
      index - the new starting index
      entry - the single entry to store
      Throws:
      IOException - if the log cannot be reinitialized

    • deleteAllEntriesStartingFrom

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

    • forEach

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

    • forEach

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

    • sizeInBytes

      public long sizeInBytes()
      Description copied from interface: Log
      Returns the approximate size of the log data in bytes.
      Specified by:
      sizeInBytes in interface Log
      Returns:
      the size in bytes

    • findCapability

      public <T extends LogCapability> T findCapability(Class<T> capability)
      Description copied from interface: Log
      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.

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

    • toString

      public String toString()
      Overrides:
      toString in class Object