Table of Contents

Interface IScheduleStore

Namespace
Excalibur.Dispatch.Delivery
Assembly
Excalibur.Dispatch.Abstractions.dll

Defines the contract for storage and retrieval of scheduled messages with lifecycle management.

public interface IScheduleStore
Extension Methods

Remarks

This administrative API alone does not guarantee durable storage, transactional execution admission, distributed ownership or exactly-once delivery. Providers declare persistence guarantees separately. A scheduler requiring atomic admission must use IScheduleExecutionStore on this same configured store. Administrative replacement and completion invalidate prior execution authority when that capability is supported; detached inventory snapshots are observations, not write authority.

Methods

CompleteAsync(Guid, CancellationToken)

Marks a scheduled message as completed and removes it from active scheduling.

Task CompleteAsync(Guid scheduleId, CancellationToken cancellationToken)

Parameters

scheduleId Guid

The unique identifier of the scheduled message to complete.

cancellationToken CancellationToken

Token to observe for cancellation requests during the completion operation.

Returns

Task

A task representing the asynchronous completion operation.

Remarks

This method handles the lifecycle completion of scheduled messages, typically called after successful message execution or when a schedule should no longer be processed.

Completion Scenarios:

Schedules are completed in various situations:

  • One-time schedules after successful execution
  • Recurring schedules that have reached their end condition
  • Schedules explicitly cancelled by administrative action
  • Failed schedules that have exhausted retry attempts.

Data Handling:

Completion behavior depends on implementation requirements:

  • Hard delete: Permanently remove the schedule record
  • Soft delete: Mark as inactive while preserving for audit
  • Archive: Move to historical storage for compliance
  • Cascade: Handle related execution history and metadata.

Idempotency:

This operation should be idempotent - completing an already completed or non-existent schedule should not result in errors, enabling safe retry scenarios and distributed processing coordination.

Exceptions

OperationCanceledException

Thrown when the operation is cancelled.

InvalidOperationException

Thrown when the store is in an invalid state for completion operations.

GetAllAsync(CancellationToken)

Retrieves all scheduled messages from the store for processing and management.

Task<IEnumerable<IScheduledMessage>> GetAllAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to observe for cancellation requests during the retrieval operation.

Returns

Task<IEnumerable<IScheduledMessage>>

A task representing the asynchronous operation, with the result containing an enumerable collection of all scheduled messages in the store.

Remarks

This method provides access to the complete schedule inventory for various scenarios:

Use Cases:

  • Scheduler initialization and full schedule discovery
  • Administrative tools for schedule management and monitoring
  • Migration and backup operations
  • Debugging and troubleshooting scheduled message issues.

Performance Considerations:

This method may return large result sets in production environments with many schedules. Implementations should consider:

  • Streaming results for memory efficiency
  • Pagination support for large datasets
  • Read-only snapshots for consistency
  • Connection pooling and timeout handling.

Filtering and Ordering:

Results are typically ordered by next execution time to optimize scheduler processing, though specific ordering guarantees depend on the implementation.

Exceptions

OperationCanceledException

Thrown when the operation is cancelled.

InvalidOperationException

Thrown when the store is in an invalid state for reading.

StoreAsync(IScheduledMessage, CancellationToken)

Stores a scheduled message in the configured store for future execution.

Task StoreAsync(IScheduledMessage message, CancellationToken cancellationToken)

Parameters

message IScheduledMessage

The scheduled message to store. Cannot be null and must have a valid ID.

cancellationToken CancellationToken

Token to observe for cancellation requests during the store operation.

Returns

Task

A task representing the asynchronous storage operation.

Remarks

This method provides idempotent storage for scheduled messages, handling both new schedule creation and updates to existing schedules based on the message ID.

Storage Behavior:

The implementation should:

  • Create new schedules for unknown IDs
  • Update existing schedules for known IDs (upsert semantics)
  • Validate message data integrity before storage
  • Ensure atomic operations for consistency.

Data Validation:

Before storage, the implementation should validate:

  • Required fields are populated (ID, MessageBody, MessageName)
  • Cron expressions are valid if provided
  • Timezone IDs are recognized if specified
  • Next execution times are calculated correctly.

Concurrency Handling:

The store must handle concurrent access scenarios including:

  • Multiple scheduler instances updating the same schedule
  • Administrative tools modifying schedules during execution
  • Bulk operations competing with individual updates.

Exceptions

ArgumentNullException

Thrown when message is null.

ArgumentException

Thrown when message contains invalid data.

OperationCanceledException

Thrown when the operation is cancelled.

InvalidOperationException

Thrown when the store is in an invalid state for writing.