Interface Snapshotable

All Known Implementing Classes:
DistributedMap, DistributedMultiMap
public interface Snapshotable
Interface for data structures that can be snapshotted and restored.

Implementations should provide serialization of their current state and ability to restore from that serialized state. Used by StateMachineSnapshotManager for Raft log compaction.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Snapshotable.SnapshotCapture
    Serialized snapshot bytes plus an optional dirty-state token for rollback.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Snapshotable.SnapshotCapture
    captureDeltaSnapshot()
    Capture a delta snapshot and atomically advance dirty tracking for the captured state.
    default Snapshotable.SnapshotCapture
    captureSnapshot()
    Capture a full snapshot and atomically advance dirty tracking for the captured state.
    default void
    clearDirtyState()
    Clear the dirty-tracking state after a delta snapshot has been persisted.
    default boolean
    hasDirtyState()
    Whether any data has changed since the last snapshot.
    void
    restoreSnapshot(byte[] data)
    Restore this data structure from a previously serialized state.
    default void
    rollbackDirtyState(@Nullable Object dirtyStateToken)
    Restore dirty-tracking state that was detached during snapshot capture.
    String
    snapshotId()
    Get a unique identifier for this data structure.
    default boolean
    supportsDeltaSnapshot()
    Whether this data structure supports delta (incremental) snapshots.
    default byte[]
    takeDeltaSnapshot()
    Serialize only the changed state since the last snapshot into a byte array.
    byte[]
    takeSnapshot()
    Serialize the current state of this data structure into a byte array.

  • Method Details

    • takeSnapshot

      byte[] takeSnapshot()
      Serialize the current state of this data structure into a byte array.
      Returns:
      byte array containing the serialized state

    • restoreSnapshot

      void restoreSnapshot(byte[] data)
      Restore this data structure from a previously serialized state.

      Must restore the state atomically, clearing existing data and populating with the snapshot contents.

      Parameters:
      data - the serialized state to restore from

    • snapshotId

      String snapshotId()
      Get a unique identifier for this data structure.

      Used to identify which data structure a snapshot belongs to in a full state machine snapshot.

      Returns:
      unique identifier for this data structure

    • supportsDeltaSnapshot

      default boolean supportsDeltaSnapshot()
      Whether this data structure supports delta (incremental) snapshots.

      Structures that return true must also implement takeDeltaSnapshot() and clearDirtyState().

      Returns:
      true if delta snapshots are supported

    • captureSnapshot

      default Snapshotable.SnapshotCapture captureSnapshot()
      Capture a full snapshot and atomically advance dirty tracking for the captured state.

      Implementations that detach dirty state must return a token so the caller can restore it if snapshot serialization or persistence later fails.

      Returns:
      captured snapshot data and optional rollback token

    • takeDeltaSnapshot

      default byte[] takeDeltaSnapshot()
      Serialize only the changed state since the last snapshot into a byte array.

      Only called when supportsDeltaSnapshot() returns true. The default implementation falls back to a full snapshot.

      Returns:
      byte array containing only changed state, or empty if no changes

    • captureDeltaSnapshot

      default Snapshotable.SnapshotCapture captureDeltaSnapshot()
      Capture a delta snapshot and atomically advance dirty tracking for the captured state.

      Implementations that detach dirty state must return a token so the caller can restore it if snapshot serialization or persistence later fails.

      Returns:
      captured delta data and optional rollback token

    • clearDirtyState

      default void clearDirtyState()
      Clear the dirty-tracking state after a delta snapshot has been persisted.

      Called after a successful delta snapshot to reset change tracking. Default implementation is a no-op.

    • rollbackDirtyState

      default void rollbackDirtyState(@Nullable Object dirtyStateToken)
      Restore dirty-tracking state that was detached during snapshot capture.

      Called only when snapshot persistence fails after a capture completed successfully.

      Parameters:
      dirtyStateToken - implementation-specific token returned by captureSnapshot/captureDeltaSnapshot

    • hasDirtyState

      default boolean hasDirtyState()
      Whether any data has changed since the last snapshot.

      Used by the snapshot scheduler to skip structures with no changes during delta snapshots.

      Returns:
      true if changes exist since last clearDirtyState() call