Table of Contents

Class OracleSagaStore

Namespace
Excalibur.Saga.Oracle
Assembly
Excalibur.Saga.Oracle.dll

Oracle implementation of ISagaStore for managing saga state persistence.

public sealed class OracleSagaStore : ISagaStore, IServiceProvider, ISagaStoreAdmin
Inheritance
OracleSagaStore
Implements
Inherited Members

Remarks

Provides durable storage for saga state with optimistic concurrency control using a numeric Version compare-and-swap. Mirrors the SQL Server store; Oracle-specific SQL (MERGE with FROM DUAL, colon-prefixed bind variables, SYS_EXTRACT_UTC(SYSTIMESTAMP)) is inlined per the persistence-seam ruling.

Constructors

OracleSagaStore(Func<OracleConnection>, ILogger<OracleSagaStore>, DispatchJsonSerializer, ITenantContext)

Initializes a new instance of the OracleSagaStore class with a connection factory.

public OracleSagaStore(Func<OracleConnection> connectionFactory, ILogger<OracleSagaStore> logger, DispatchJsonSerializer serializer, ITenantContext tenantContext)

Parameters

connectionFactory Func<OracleConnection>

A factory that creates Oracle.ManagedDataAccess.Client.OracleConnection instances.

logger ILogger<OracleSagaStore>

The logger instance.

serializer DispatchJsonSerializer

The JSON serializer for saga state serialization.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

OracleSagaStore(Func<OracleConnection>, IOptions<OracleSagaStoreOptions>, ILogger<OracleSagaStore>, DispatchJsonSerializer, ITenantContext)

Initializes a new instance of the OracleSagaStore class with a connection factory and options.

public OracleSagaStore(Func<OracleConnection> connectionFactory, IOptions<OracleSagaStoreOptions> options, ILogger<OracleSagaStore> logger, DispatchJsonSerializer serializer, ITenantContext tenantContext)

Parameters

connectionFactory Func<OracleConnection>

A factory that creates Oracle.ManagedDataAccess.Client.OracleConnection instances.

options IOptions<OracleSagaStoreOptions>

The saga store options.

logger ILogger<OracleSagaStore>

The logger instance.

serializer DispatchJsonSerializer

The JSON serializer for saga state serialization.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

OracleSagaStore(string, ILogger<OracleSagaStore>, DispatchJsonSerializer, ITenantContext)

Initializes a new instance of the OracleSagaStore class.

public OracleSagaStore(string connectionString, ILogger<OracleSagaStore> logger, DispatchJsonSerializer serializer, ITenantContext tenantContext)

Parameters

connectionString string

The Oracle connection string.

logger ILogger<OracleSagaStore>

The logger instance.

serializer DispatchJsonSerializer

The JSON serializer for saga state serialization.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

OracleSagaStore(string, IOptions<OracleSagaStoreOptions>, ILogger<OracleSagaStore>, DispatchJsonSerializer, ITenantContext)

Initializes a new instance of the OracleSagaStore class with options.

public OracleSagaStore(string connectionString, IOptions<OracleSagaStoreOptions> options, ILogger<OracleSagaStore> logger, DispatchJsonSerializer serializer, ITenantContext tenantContext)

Parameters

connectionString string

The Oracle connection string.

options IOptions<OracleSagaStoreOptions>

The saga store options.

logger ILogger<OracleSagaStore>

The logger instance.

serializer DispatchJsonSerializer

The JSON serializer for saga state serialization.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

Methods

GetAllTenantsStatisticsAsync(CancellationToken)

Gets aggregate statistics about the sagas of every tenant (running / completed / total counts).

public ValueTask<SagaStoreStatistics> GetAllTenantsStatisticsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<SagaStoreStatistics>

The saga store statistics across all tenant partitions.

Remarks

This is the operator diagnostic: no tenant discriminator is applied, so every tenant's sagas are counted. It is the only statistics read that runs without a resolved tenant, because it is the only one that does not need to name one.

The name is the safety control. Estate-wide counts are reachable only by writing "AllTenants" at the call site, never by omitting a scope or by passing a value that happens to mean "everything" — the same discipline as PurgeAllTenantsCompletedBeforeAsync(DateTimeOffset, CancellationToken). A caller cannot arrive here by forgetting something, and a reviewer reading the call site sees the intent without tracing where a scope came from.

Aggregate counts disclose no saga identifiers, types, or tenant names — only totals — so this is a weaker disclosure than QuerySagasAsync(SagaQueryFilter, CancellationToken), which stays tenant-scoped and has no estate-wide counterpart.

Like the estate-wide purge this is an optional capability whose default implementation throws. A store that supports it overrides this method; a decorator must override it to forward to its inner store — a decorator that does not override inherits this throwing default, so a decorated store would report the capability as missing even though the store underneath supports it.

Exceptions

NotSupportedException

Thrown by stores that do not support estate-wide statistics.

GetStatisticsAsync(CancellationToken)

Gets aggregate statistics about the calling tenant's sagas (running / completed / total counts).

public ValueTask<SagaStoreStatistics> GetStatisticsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<SagaStoreStatistics>

The saga store statistics for the ambient tenant partition.

Remarks

The counts are tenant-scoped: they cover the ambient partition and no other. A host that established no tenant operates on the untenanted partition, which is a real partition holding the rows that carry no tenant — not a wildcard, and not every tenant's rows. Estate-wide counts are a deliberately separate operation, GetAllTenantsStatisticsAsync(CancellationToken).

GetSummaryAsync(Guid, CancellationToken)

Gets the summary of a single saga instance by its identifier.

public ValueTask<SagaInstanceSummary?> GetSummaryAsync(Guid sagaId, CancellationToken cancellationToken)

Parameters

sagaId Guid

The unique identifier of the saga instance.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<SagaInstanceSummary>

The saga instance summary, or null when no such saga exists.

LoadAsync<TSagaState>(Guid, CancellationToken)

Asynchronously loads the saga state for the specified saga identifier from persistent storage. This method enables saga recovery and continuation of business processes across system boundaries.

public Task<TSagaState?> LoadAsync<TSagaState>(Guid sagaId, CancellationToken cancellationToken) where TSagaState : SagaState

Parameters

sagaId Guid

The unique identifier of the saga instance to load.

cancellationToken CancellationToken

Token to monitor for cancellation requests during load operations.

Returns

Task<TSagaState>

A task that represents the asynchronous load operation, containing the saga state if found, or null if no saga with the specified identifier exists in storage.

Type Parameters

TSagaState

The type of saga state to load, must inherit from SagaState.

Remarks

Implementations should handle storage-specific error conditions gracefully and may implement caching strategies for performance optimization. The method should preserve saga state integrity and handle concurrent access scenarios appropriately. Failed loads due to storage issues should propagate exceptions to enable proper error handling in the saga coordination layer.

Confined to the ambient tenant established for this store instance: resolves the caller's own saga state for sagaId when it exists, and never resolves state stored under another tenant's identical sagaId — such a lookup returns null, the same outcome as a genuinely missing saga.

PurgeAllTenantsCompletedBeforeAsync(DateTimeOffset, CancellationToken)

Asynchronously purges completed saga instances across every tenant, ignoring any tenant scope the store would otherwise apply. This is the operator-level retention sweep.

public Task<int> PurgeAllTenantsCompletedBeforeAsync(DateTimeOffset threshold, CancellationToken cancellationToken)

Parameters

threshold DateTimeOffset

The exclusive upper bound on completion time. Only sagas that are completed and whose CompletedAt is strictly before this instant are purged.

cancellationToken CancellationToken

Token to monitor for cancellation requests during the purge operation.

Returns

Task<int>

A task that represents the asynchronous purge operation, containing the total number of saga instances removed across all tenants.

Remarks

Eligibility is identical to PurgeCompletedBeforeAsync(DateTimeOffset, CancellationToken) — only terminated sagas older than threshold are removed — but no tenant discriminator is applied, so every tenant's rows are in range. This is also the only purge that runs without a resolved tenant, because it is the only one that does not need to name one.

The name is the safety control. Cross-tenant deletion is reachable only by writing "AllTenants" at the call site, never by omitting a scope or by passing a value that happens to mean "everything". A caller cannot arrive here by forgetting something, and a reviewer reading the call site sees the intent without having to trace where a scope came from.

Like the scoped purge this is an optional capability whose default implementation throws. A store that supports it overrides this method; a decorator must override it to forward to its inner store — a decorator that does not override inherits this throwing default, so a decorated store would report the capability as missing even though the store underneath supports it.

Exceptions

NotSupportedException

Thrown by stores that do not support estate-wide purge-by-age.

PurgeCompletedBeforeAsync(DateTimeOffset, CancellationToken)

Asynchronously purges completed saga instances whose completion time is strictly earlier than the specified threshold, reclaiming storage for terminated business processes that no longer need to be retained.

public Task<int> PurgeCompletedBeforeAsync(DateTimeOffset threshold, CancellationToken cancellationToken)

Parameters

threshold DateTimeOffset

The exclusive upper bound on completion time. Only sagas that are completed and whose CompletedAt is strictly before this instant are purged.

cancellationToken CancellationToken

Token to monitor for cancellation requests during the purge operation.

Returns

Task<int>

A task that represents the asynchronous purge operation, containing the number of saga instances removed from storage.

Remarks

Only sagas that have reached a terminal state (Completed is true with a non-null CompletedAt) are eligible. Running sagas, and completed sagas whose completion instant is at or after threshold, are never removed. Implementations must perform the purge atomically with respect to concurrent saves and return the exact count removed so callers can drive retention policies and emit metrics.

Purge-by-age is an optional capability. The default implementation throws NotSupportedException — a store that cannot purge by completion age fails loud rather than silently pretending it purged (returning 0 would hide the missing capability from a retention scheduler). Stores that support it (the in-memory store and the first-party persistence providers) override this method with a real purge; a decorator overrides it to forward to its inner store.

This purge is tenant-scoped. It removes only sagas belonging to the store's own scope: the ambient tenant when one is resolved, or the untenanted partition — the sagas carrying no tenant at all — when none is. Both are real scopes, so rows written without a tenant stay reachable for retention instead of accumulating forever, and neither scope can reach the other's rows. Estate-wide retention — deleting completed sagas across every tenant — is a deliberately separate operation, PurgeAllTenantsCompletedBeforeAsync(DateTimeOffset, CancellationToken), because cross-tenant deletion must be something a caller states explicitly rather than something reached by omitting a scope.

Exceptions

NotSupportedException

Thrown by stores that do not support purge-by-age.

QuerySagasAsync(SagaQueryFilter, CancellationToken)

Queries saga instance summaries matching the supplied filter, ordered by store-defined ordering, with pagination.

public ValueTask<IReadOnlyList<SagaInstanceSummary>> QuerySagasAsync(SagaQueryFilter filter, CancellationToken cancellationToken)

Parameters

filter SagaQueryFilter

The filter criteria (completion state, tenant, pagination).

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<IReadOnlyList<SagaInstanceSummary>>

The matching saga instance summaries.

Exceptions

ArgumentNullException

Thrown when filter is null.

SaveAsync<TSagaState>(TSagaState, CancellationToken)

Asynchronously persists the specified saga state to durable storage, ensuring business process continuity and enabling recovery across system failures or restarts.

[RequiresUnreferencedCode("Saga state is serialized with a reflection-based serializer that may require types which cannot be statically analyzed.")]
[RequiresDynamicCode("Saga state is serialized with a reflection-based serializer, which generates converters at run time.")]
public Task SaveAsync<TSagaState>(TSagaState sagaState, CancellationToken cancellationToken) where TSagaState : SagaState

Parameters

sagaState TSagaState

The saga state instance containing current business process data and status.

cancellationToken CancellationToken

Token to monitor for cancellation requests during save operations.

Returns

Task

A task that represents the asynchronous save operation.

Type Parameters

TSagaState

The type of saga state to save, must inherit from SagaState.

Remarks

Implementations must ensure transactional consistency and handle concurrent modification scenarios appropriately, potentially using optimistic concurrency control or version-based conflict resolution. The save operation should be atomic and durable, guaranteeing that saga state changes are reliably persisted before the operation completes. Failed saves should propagate exceptions to enable proper error handling and potential retry logic in calling code.

Confined to the ambient tenant established for this store instance: the save can neither overwrite another tenant's saga state for the same identifier nor be overwritten by one — the two occupy separate partitions even when every other field is identical.