Package io.axoniq.framework.messaging.eventstreaming.checkpoint

Class CheckpointingProgressStrategy

java.lang.Object
io.axoniq.framework.messaging.eventstreaming.checkpoint.CheckpointingProgressStrategy
All Implemented Interfaces:
SegmentProgressStrategy
@Internal public final class CheckpointingProgressStrategy extends Object implements SegmentProgressStrategy
SegmentProgressStrategy that lets self-checkpointing Checkpointing units manage when their segment's stored TrackingToken advances. The progress-persistence counterpart of the self-checkpointing protocol: it collects the safe positions reported by the segment's participants, reconciles them to a single agreed token, and persists that through the SegmentProgressContext.

It runs in one of two modes, fixed per processor at construction:

  • Auto (autoCheckpointing == true): at least one ordinary handler is co-located with the participants, so a checkpoint at the batch-end token is requested every batch and the participants are driven to cover it; they cannot defer the stored token.
  • Fully-deferred (autoCheckpointing == false): every handler is a participant, so the stored token advances only on an explicit CheckpointTrigger request.

Internal API. This class is marked Internal: it is part of the self-checkpointing support, intended primarily for internal and advanced use, and its shape may change in a minor or patch release.

Since:
5.3.0
Author:
Allard Buijze
See Also:

  • Constructor Details

    • CheckpointingProgressStrategy

      public CheckpointingProgressStrategy(SegmentProgressContext context, List<Checkpointing> participants, boolean autoCheckpointing)
      Constructs a CheckpointingProgressStrategy bound to the given context.
      Parameters:
      context - the work package's progress context to persist progress through
      participants - the self-checkpointing units on this segment; must not be empty
      autoCheckpointing - true when an ordinary handler is co-located (auto mode), false when every handler is self-checkpointing (fully-deferred)

  • Method Details

    • contributeBatchResources

      public void contributeBatchResources(ProcessingContext processingContext)
      Description copied from interface: SegmentProgressStrategy
      Contributes per-batch resources to context before the batch is handled, for example a handle a handler may use to influence persistence (such as a checkpoint trigger). Invoked only for non-empty batches, before invocation. Defaults to a no-op.
      Specified by:
      contributeBatchResources in interface SegmentProgressStrategy
      Parameters:
      processingContext - the processing context of the batch about to be handled

    • onBatchCommit

      public CompletableFuture<Void> onBatchCommit(ProcessingContext processingContext)
      Decides which token (if any) to store for this cycle and persists it through the context.
      • Auto mode checkpoints at the batch-end token (lastConsumedToken); a participant is therefore forced to cover it.
      • Fully-deferred mode stores only when a participant explicitly requested a checkpoint.
      The participants are reconciled to a single agreed position before storing, so no participant is left ahead of the stored token. A store is skipped when nothing is to be checkpointed.
      Specified by:
      onBatchCommit in interface SegmentProgressStrategy
      Parameters:
      processingContext - the processing context whose transaction the store participates in
      Returns:
      a CompletableFuture completing when the cycle's persistence (if any) has been applied

    • hasPendingWork

      public boolean hasPendingWork()
      Description copied from interface: SegmentProgressStrategy
      Indicates whether the strategy has out-of-band work that requires a worker cycle even when no events are queued (for example, an asynchronous checkpoint request recorded between cycles). Drives the post-cycle reschedule and lets an idle segment run a commit cycle. Strategies that act only within their batches never schedule out-of-band and return false; this is deliberately not a throttle for idle catch-up stores, which are driven on the claim-extension beat.
      Specified by:
      hasPendingWork in interface SegmentProgressStrategy
      Returns:
      true if a worker cycle is needed for out-of-band work, false otherwise

    • onSegmentClaimed

      public void onSegmentClaimed()
      Description copied from interface: SegmentProgressStrategy
      Invoked when the segment is claimed, before any events are handled. Defaults to a no-op.
      Specified by:
      onSegmentClaimed in interface SegmentProgressStrategy

    • onSegmentReleased

      public CompletableFuture<Void> onSegmentReleased(ProcessingContext processingContext)
      Performs the final checkpoint for the segment being released: asks each participant to drain toward lastConsumedToken through Checkpointing.onSegmentReleased(Segment, TrackingToken), then reconciles their reported positions to a single agreed token and persists that within the given context (if it advances). Only when reconciliation cannot be reached (a lagging participant fails to cover the agreed position) does it fall back to persisting the lowerBound of the reported tokens, so the claim can still be released and the uncovered tail is simply reprocessed on the next claim.
      Specified by:
      onSegmentReleased in interface SegmentProgressStrategy
      Parameters:
      processingContext - the processing context whose transaction the final store participates in
      Returns:
      a CompletableFuture completing when the final persistence (if any) has been applied

    • onAbort

      public void onAbort()
      Description copied from interface: SegmentProgressStrategy
      Invoked when processing of the segment aborts, so the strategy can deactivate any out-of-band signal (for example, render a checkpoint trigger inert so a late request becomes a no-op). Defaults to a no-op.
      Specified by:
      onAbort in interface SegmentProgressStrategy