Class DurableLogBuilder

java.lang.Object
org.j7m.middleware.durablelog.DurableLogBuilder
public final class DurableLogBuilder extends Object
Builder for FileDurableLog.

The builder opens the file-backed durable log and performs production recovery before returning it. The default recovery policy is fail-fast: an incomplete or corrupt tail rejects the open instead of modifying storage. Callers that are intentionally performing crash-tail repair must opt in with truncateTailRecovery() or recoveryOptions(RecoveryOptions). Instances are mutable and not thread-safe.

  • Constructor Details

    • DurableLogBuilder

      public DurableLogBuilder()
      Creates a builder with default settings.

  • Method Details

    • directory

      public DurableLogBuilder directory(Path value)
      Selects the storage directory opened and recovered by build(). The directory is required; this setter does not open files or validate the path.
      Parameters:
      value - required log directory; a null value is rejected when building
      Returns:
      this builder

    • maxSegmentBytes

      public DurableLogBuilder maxSegmentBytes(long value)
      Sets the segment rotation threshold in bytes; the default is 16 MiB. Values below 4096 bytes are rejected by build().
      Parameters:
      value - maximum segment size
      Returns:
      this builder

    • maxPayloadBytes

      public DurableLogBuilder maxPayloadBytes(long value)
      Sets the per-record payload limit in bytes; the default is 1 MiB. Zero permits only empty payloads; negative values fail at build().
      Parameters:
      value - maximum payload size
      Returns:
      this builder

    • maxRecordsPerAppend

      public DurableLogBuilder maxRecordsPerAppend(int value)
      Sets the maximum number of records accepted by one append; the default is 1024. The value must be positive and is validated by build().
      Parameters:
      value - maximum records per append call
      Returns:
      this builder

    • maxOpenCursors

      public DurableLogBuilder maxOpenCursors(int value)
      Sets the maximum simultaneously open read cursors; the default is 128. The value must be positive and is validated by build().
      Parameters:
      value - maximum concurrently open cursors
      Returns:
      this builder

    • fsyncPolicy

      public DurableLogBuilder fsyncPolicy(org.j7m.middleware.api.durablelog.FsyncPolicy value)
      Selects when accepted writes are synchronized to storage. The default, also used for a null value at build time, is PER_APPEND.
      Parameters:
      value - fsync policy
      Returns:
      this builder

    • groupCommitPolicy

      public DurableLogBuilder groupCommitPolicy(org.j7m.middleware.api.durablelog.GroupCommitPolicy value)
      Configures finite batching for group synchronization. A null value selects GroupCommitPolicy.defaults() at build time.
      Parameters:
      value - group commit policy
      Returns:
      this builder

    • integrityPolicy

      public DurableLogBuilder integrityPolicy(org.j7m.middleware.api.durablelog.LogIntegrityPolicy value)
      Selects frame-integrity verification for the opened log. A null value selects CHECKSUM_ONLY at build time.
      Parameters:
      value - integrity policy
      Returns:
      this builder

    • retentionPolicy

      public DurableLogBuilder retentionPolicy(org.j7m.middleware.api.durablelog.RetentionPolicy value)
      Selects segment retention for the opened log. Retention is disabled by default and when a null value is built.
      Parameters:
      value - retention policy
      Returns:
      this builder

    • clock

      public DurableLogBuilder clock(Clock value)
      Supplies the timestamp source borrowed by the opened log. A null value selects Clock.systemUTC() at build time.
      Parameters:
      value - timestamp source
      Returns:
      this builder

    • recoveryOptions

      public DurableLogBuilder recoveryOptions(org.j7m.middleware.api.durablelog.RecoveryOptions value)
      Sets recovery options used during build().

      Passing null restores the fail-fast default. Tail truncation is a destructive repair action and should be selected only for crash-repair paths that have already accepted dropping the incomplete final frame.

      Parameters:
      value - recovery options for the open path
      Returns:
      this builder

    • truncateTailRecovery

      public DurableLogBuilder truncateTailRecovery()
      Selects explicit crash-tail truncation recovery for build().
      Returns:
      this builder

    • build

      public FileDurableLog build()
      Opens the configured directory and recovers its durable state before returning ownership.

      Configuration is validated at this point, not by the fluent setters. Default recovery fails on an incomplete or corrupt tail; explicit tail truncation can discard an incomplete final frame. On recovery failure the opened log is closed, and any close failure is attached as a suppressed exception. The caller must close a successfully returned log.

      Returns:
      opened and recovered durable log owned by the caller
      Throws:
      IllegalArgumentException - if the directory or configured size/count bounds are invalid
      RuntimeException - if opening storage or recovering the selected journal fails