Interface SagaService

All Superinterfaces:
AutoCloseable
public interface SagaService extends AutoCloseable
J7M-native durable saga orchestration service.

Implementations own durable saga definition metadata, execution state, retry state, timeout state, cancellation state, evidence, dead-letter summaries, and durable outbox command intent. Methods may block on local durable-log append/replay and outbox operations. The service is not a global transaction manager and does not promise universal single-effect execution.

Implementations must be thread-safe or document narrower ownership. All public status and evidence returned by this interface must be redacted. After recovery, executable action callbacks must be re-registered before non-terminal executions can continue; recovered in-flight work must either resume through a documented idempotent retry/compensation path or report a safe waiting state. Invalid definitions, unknown executions, overload, recovery failures, durable-log failures, outbox failures, and closed-service access must map to stable middleware error codes.

  • Method Details

    • register

      void register(SagaDefinition definition)
      Registers or validates a saga definition.

      Registration links durable definition metadata to executable Java actions. After recovery, callers must register the same definition and step identifiers to resume non-terminal executions.

      Parameters:
      definition - executable definition to register
      Throws:
      SagaException - if durable registration fails or the definition is invalid

    • start

      SagaStartResult start(SagaStartRequest request)
      Starts a saga execution.
      Parameters:
      request - start request including definition id, options, context, and payload
      Returns:
      durable start result, including duplicate status when idempotency matched
      Throws:
      SagaException - if the execution cannot be started

    • runUntilIdle

      SagaExecution runUntilIdle(SagaExecutionId executionId)
      Runs eligible saga work deterministically until blocked or terminal.

      The method records outbox command intent before dispatching a step action. It may stop when executable actions are missing, retry delay has not elapsed, cancellation is pending, or a terminal state is reached. Implementations must preserve idempotency metadata across recovery so retrying recovered work does not become a generic exactly-once claim.

      Parameters:
      executionId - execution to advance
      Returns:
      redacted execution status after work is drained or blocked
      Throws:
      SagaException - if durable state cannot be advanced

    • cancel

      SagaCancelResult cancel(SagaCancelRequest request)
      Requests saga cancellation.
      Parameters:
      request - cancellation request
      Returns:
      cancellation result after the durable request is recorded
      Throws:
      SagaException - if the cancellation cannot be recorded

    • evaluateTimeouts

      void evaluateTimeouts()
      Evaluates deterministic timeout transitions.

      Both saga-level and step-level timeouts are evaluated using the implementation clock; callers should use a mutable/test clock for deterministic validation rather than sleeps.

      Throws:
      SagaException - if timeout evaluation cannot persist required events

    • status

      SagaStatus status()
      Returns safe service status.

      The status is a redacted summary containing metrics, per-execution state, retained evidence, dead-letter summaries, and recovery diagnostics. It must not expose command payload bytes, credentials, or full internal transaction contexts.

      Returns:
      immutable redacted status snapshot

    • execution

      SagaExecution execution(SagaExecutionId executionId)
      Returns a safe execution summary.
      Parameters:
      executionId - execution identifier
      Returns:
      immutable redacted execution summary
      Throws:
      SagaException - if the execution is unknown

    • close

      void close()
      Closes owned resources.

      Implementations should make the operation idempotent. After close, mutating operations may reject with a stable saga error.

      Specified by:
      close in interface AutoCloseable