Class OracleSagaStore
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
connectionFactoryFunc<OracleConnection>A factory that creates Oracle.ManagedDataAccess.Client.OracleConnection instances.
loggerILogger<OracleSagaStore>The logger instance.
serializerDispatchJsonSerializerThe JSON serializer for saga state serialization.
tenantContextITenantContextThe 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
connectionFactoryFunc<OracleConnection>A factory that creates Oracle.ManagedDataAccess.Client.OracleConnection instances.
optionsIOptions<OracleSagaStoreOptions>The saga store options.
loggerILogger<OracleSagaStore>The logger instance.
serializerDispatchJsonSerializerThe JSON serializer for saga state serialization.
tenantContextITenantContextThe 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
connectionStringstringThe Oracle connection string.
loggerILogger<OracleSagaStore>The logger instance.
serializerDispatchJsonSerializerThe JSON serializer for saga state serialization.
tenantContextITenantContextThe 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
connectionStringstringThe Oracle connection string.
optionsIOptions<OracleSagaStoreOptions>The saga store options.
loggerILogger<OracleSagaStore>The logger instance.
serializerDispatchJsonSerializerThe JSON serializer for saga state serialization.
tenantContextITenantContextThe 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
cancellationTokenCancellationTokenToken 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
cancellationTokenCancellationTokenToken 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
sagaIdGuidThe unique identifier of the saga instance.
cancellationTokenCancellationTokenToken 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
sagaIdGuidThe unique identifier of the saga instance to load.
cancellationTokenCancellationTokenToken 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
nullif no saga with the specified identifier exists in storage.
Type Parameters
TSagaStateThe 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
thresholdDateTimeOffsetThe exclusive upper bound on completion time. Only sagas that are completed and whose CompletedAt is strictly before this instant are purged.
cancellationTokenCancellationTokenToken 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
thresholdDateTimeOffsetThe exclusive upper bound on completion time. Only sagas that are completed and whose CompletedAt is strictly before this instant are purged.
cancellationTokenCancellationTokenToken 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
filterSagaQueryFilterThe filter criteria (completion state, tenant, pagination).
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask<IReadOnlyList<SagaInstanceSummary>>
The matching saga instance summaries.
Exceptions
- ArgumentNullException
Thrown when
filteris 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
sagaStateTSagaStateThe saga state instance containing current business process data and status.
cancellationTokenCancellationTokenToken to monitor for cancellation requests during save operations.
Returns
- Task
A task that represents the asynchronous save operation.
Type Parameters
TSagaStateThe 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.