Class SnapshotStore

java.lang.Object
com.loomcache.server.persistence.SnapshotStore
public class SnapshotStore extends Object
Snapshot storage for Raft log compaction.

Saves/loads snapshots to disk: snapshot-{nodeId}-{index}.bin Format: [snapshotIndex(8)][snapshotTerm(8)][dataLength(4)][data][sha256Checksum(32)]

Records snapshot metadata: index, term, data, and SHA-256 checksum for validation.

  • Constructor Details

    • SnapshotStore

      public SnapshotStore(String nodeId, Path snapshotDirectory) throws IOException
      Initialize snapshot store.
      Parameters:
      nodeId - The node identifier
      snapshotDirectory - The directory path for snapshots
      Throws:
      IOException - If directory creation fails

    • SnapshotStore

      public SnapshotStore(String nodeId, Path snapshotDirectory, @Nullable LoomMetrics metrics) throws IOException
      Initialize snapshot store with metrics.
      Parameters:
      nodeId - The node identifier
      snapshotDirectory - The directory path for snapshots
      metrics - Optional metrics tracker
      Throws:
      IOException - If directory creation fails

  • Method Details

    • saveSnapshot

      public void saveSnapshot(long index, long term, byte[] data) throws IOException
      Save a snapshot to disk with SHA-256 checksum.

      Format: [snapshotIndex(8)][snapshotTerm(8)][dataLength(4)][data][sha256Checksum(32)]

      Parameters:
      index - The snapshot index
      term - The snapshot term
      data - The snapshot data (must not be null; use an empty array for a zero-length snapshot)
      Throws:
      NullPointerException - If data is null
      IOException - If write fails

    • stageSnapshot

      public SnapshotStore.StagedSnapshot stageSnapshot(long index, long term, byte[] data) throws IOException
      Throws:
      IOException

    • promoteStagedSnapshot

      public void promoteStagedSnapshot(SnapshotStore.StagedSnapshot stagedSnapshot) throws IOException
      Throws:
      IOException

    • discardStagedSnapshot

      public void discardStagedSnapshot(@Nullable SnapshotStore.StagedSnapshot stagedSnapshot)

    • loadLatestSnapshot

      public Optional<SnapshotStore.SnapshotMetadata> loadLatestSnapshot() throws IOException
      Load the latest snapshot from disk.

      Finds the snapshot file with the highest index for this node. Validates SHA-256 checksum if present.

      Returns:
      Optional containing SnapshotMetadata if found and valid, empty otherwise
      Throws:
      IOException - If read fails

    • loadLatestSnapshot

      public Optional<SnapshotStore.SnapshotMetadata> loadLatestSnapshot(boolean allowFallbackToOlderSnapshot) throws IOException
      Load the latest snapshot, optionally refusing fallback when the newest snapshot exists but fails validation.
      Parameters:
      allowFallbackToOlderSnapshot - whether older snapshots may be used after the latest candidate is invalid
      Returns:
      Optional containing SnapshotMetadata if found and valid, empty otherwise
      Throws:
      IOException - If read fails or fallback is disabled and the latest candidate is invalid