Record Class RecoveryOptions

java.lang.Object
java.lang.Record
org.j7m.middleware.api.durablelog.RecoveryOptions
Record Components:
corruptionAction - action returned by corruptionAction() for corrupt or incomplete frames; null is normalized to LogCorruptionAction.FAIL
rebuildIndexes - value returned by rebuildIndexes() indicating whether recovery may rebuild missing derived indexes from durable records
maxSegmentsScanned - positive value returned by maxSegmentsScanned() for the maximum number of segment-discovery directory entries or segment files that one recovery pass may examine, in entries
maxRecordsScanned - positive value returned by maxRecordsScanned() for the maximum number of durable records that one recovery pass may reserve for replay, in records
All Implemented Interfaces:
Serializable
public record RecoveryOptions(LogCorruptionAction corruptionAction, boolean rebuildIndexes, int maxSegmentsScanned, long maxRecordsScanned) extends Record implements Serializable
Defines the bounded recovery policy used when a durable log scans existing segment storage and rebuilds derived in-memory state.

Recovery bounds are hard safety controls, not tuning hints. A recovery implementation must stop and fail closed when it cannot complete directory enumeration, segment scanning, record decoding, hash verification, or derived index/tail reconstruction within these limits. Budget exhaustion is a recovery failure; it must not be normalized silently, and it must not cause destructive tail truncation even when LogCorruptionAction.TRUNCATE_TAIL is selected for genuine corrupt or incomplete tail frames.

The segment bound limits recovery discovery work. Implementations may apply it to directory entries examined while finding segment files, so unrelated files in the log directory can consume the budget. The record bound limits the number of durable records reserved for replay and for rebuilding derived offsets, stream indexes, hash tails, checkpoint-derived service state, and similar recovery state. RecoveryOptions does not expose a separate byte budget. Byte exposure remains bounded by durable-log configuration such as maximum segment size, maximum payload size, maximum records per append, the segment discovery bound, and the record scan bound.

Services that recover from checkpoints, including messaging and coordination services, may combine these limits with service-specific checkpoint lookup and checkpoint-tail replay budgets. Histories created before suitable recovery state or checkpoints exist can fail closed when replay would exceed the configured bounds; operators must migrate or checkpoint such histories through a bounded path before they can be accepted by a bounded recovery policy.

Instances are immutable, serializable value objects and are safe to share between threads. They own no files, buffers, channels, or background work.

See Also:

  • Field Details

    • DEFAULT_MAX_SEGMENTS_SCANNED

      public static final int DEFAULT_MAX_SEGMENTS_SCANNED
      Default maximum segment-discovery entries examined by one recovery pass.

      The value is expressed in directory entries or segment files, depending on the implementation's discovery strategy.

      See Also:

    • DEFAULT_MAX_RECORDS_SCANNED

      public static final long DEFAULT_MAX_RECORDS_SCANNED
      Default maximum durable records reserved by one recovery pass.

      The value is expressed in durable records, not bytes.

      See Also:

  • Constructor Details

    • RecoveryOptions

      public RecoveryOptions(LogCorruptionAction corruptionAction, boolean rebuildIndexes, int maxSegmentsScanned, long maxRecordsScanned)
      Creates recovery options.

      The canonical constructor validates recovery bounds and normalizes a null corruption action to LogCorruptionAction.FAIL. Both scan bounds are inclusive upper limits for one recovery pass and must be at least one.

      Parameters:
      corruptionAction - action for corrupt or incomplete frames; null is normalized to LogCorruptionAction.FAIL
      rebuildIndexes - whether recovery may rebuild missing derived indexes from durable records
      maxSegmentsScanned - positive maximum number of segment-discovery directory entries or segment files that one recovery pass may examine, in entries
      maxRecordsScanned - positive maximum number of durable records that one recovery pass may reserve for replay, in records
      Throws:
      IllegalArgumentException - if maxSegmentsScanned < 1 or maxRecordsScanned < 1

    • RecoveryOptions

      public RecoveryOptions(LogCorruptionAction corruptionAction, boolean rebuildIndexes)
      Creates recovery options with the default bounded scan policy.

      The created options use DEFAULT_MAX_SEGMENTS_SCANNED and DEFAULT_MAX_RECORDS_SCANNED. A null corruption action is normalized to LogCorruptionAction.FAIL.

      Parameters:
      corruptionAction - action for corrupt or incomplete frames
      rebuildIndexes - whether recovery may rebuild missing derived indexes from durable records
      Throws:
      IllegalArgumentException - if a default bound is not positive

  • Method Details

    • defaults

      public static RecoveryOptions defaults()
      Returns safe default recovery options.

      The default policy fails recovery on corruption or incomplete frames, permits derived-index rebuild, and uses the default positive segment and record scan limits.

      Returns:
      immutable fail-closed recovery options using default bounds

    • truncateTail

      public static RecoveryOptions truncateTail()
      Returns tail-truncating recovery options for crash recovery.

      The returned policy may truncate a genuinely corrupt or incomplete tail according to durable-log recovery rules. Scan-budget exhaustion is not tail corruption and must still fail closed without destructive truncation.

      Returns:
      immutable tail-truncating recovery options using default bounds

    • bounded

      public static RecoveryOptions bounded(LogCorruptionAction corruptionAction, boolean rebuildIndexes, int maxSegmentsScanned, long maxRecordsScanned)
      Returns recovery options with explicit scan bounds.

      Use this factory when a caller needs a service-specific recovery budget, for example a checkpoint lookup budget plus a bounded tail replay budget. The segment and record limits are related but independent: segment discovery bounds how much storage is enumerated, while the record limit bounds how much durable history is replayed from the discovered segments.

      Parameters:
      corruptionAction - action for corrupt or incomplete frames; null is normalized to LogCorruptionAction.FAIL
      rebuildIndexes - whether recovery may rebuild missing derived indexes from durable records
      maxSegmentsScanned - positive maximum number of segment-discovery directory entries or segment files that one recovery pass may examine, in entries
      maxRecordsScanned - positive maximum number of durable records that one recovery pass may reserve for replay, in records
      Returns:
      immutable bounded recovery options
      Throws:
      IllegalArgumentException - if maxSegmentsScanned < 1 or maxRecordsScanned < 1

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • corruptionAction

      public LogCorruptionAction corruptionAction()
      Returns the value of the corruptionAction record component.
      Returns:
      the value of the corruptionAction record component

    • rebuildIndexes

      public boolean rebuildIndexes()
      Returns the value of the rebuildIndexes record component.
      Returns:
      the value of the rebuildIndexes record component

    • maxSegmentsScanned

      public int maxSegmentsScanned()
      Returns the value of the maxSegmentsScanned record component.
      Returns:
      the value of the maxSegmentsScanned record component

    • maxRecordsScanned

      public long maxRecordsScanned()
      Returns the value of the maxRecordsScanned record component.
      Returns:
      the value of the maxRecordsScanned record component