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

Interface CheckpointTrigger

@Internal
public interface CheckpointTrigger

Handle through which a Checkpointing unit tells the owning processor how far it is safe to advance the stored TrackingToken for a single claimed Segment. Handed to the unit on Checkpointing.onSegmentClaimed(Segment, CheckpointTrigger) and valid only for the duration of that claim.

Requesting never blocks: it wakes the segment's worker, which runs the checkpoint on the processing thread (asking every self-checkpointing component to cover the requested position and storing the single position they reconcile to, the highest any component reported, with laggards driven to also reach it). A checkpoint request is segment-scoped: it applies to all of the processor's components on that segment.

Lifecycle. The trigger is valid only for the duration of the claim. Once the segment is released (after Checkpointing.onSegmentReleased(Segment, TrackingToken)), the trigger is permanently inert: subsequent requests are silently ignored: they neither schedule the worker nor advance any stored token. After release the worker no longer holds the claim and there is no safe point to record (the segment may already be owned by another node); a late async-write acknowledgement must therefore be a no-op rather than an error. The final safe token for the claim comes solely from the return value of Checkpointing.onSegmentReleased(Segment, TrackingToken).

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

Since:

5.3.0

Author:

Allard Buijze

See Also:

• Checkpointing

Field Summary

Fields

Modifier and Type	Field	Description
static final Context.ResourceKey<CheckpointTrigger>	RESOURCE_KEY	The Context.ResourceKey under which the per-segment CheckpointTrigger is made available in the active ProcessingContext during event handling.

Method Summary

Modifier and Type	Method	Description
static Optional<CheckpointTrigger>	fromContext(Context context)	Returns an Optional of the CheckpointTrigger keyed under RESOURCE_KEY in the given context, or Optional.empty() if none is present (for example, in a processor that does not checkpoint).
default void	requestCheckpoint()	Requests a checkpoint covering everything handed to the handler so far (the segment's current lastConsumedToken).
void	requestCheckpoint(TrackingToken token)	Requests a checkpoint that must cover at least token: the component declares it is safe up to token.

Field Details

RESOURCE_KEY

static final Context.ResourceKey<CheckpointTrigger> RESOURCE_KEY

The Context.ResourceKey under which the per-segment CheckpointTrigger is made available in the active ProcessingContext during event handling. The owning processor places it there so a handler method can declare a CheckpointTrigger parameter and request checkpoints directly.

Method Details

fromContext

static Optional<CheckpointTrigger> fromContext(Context context)

Returns an Optional of the CheckpointTrigger keyed under RESOURCE_KEY in the given context, or Optional.empty() if none is present (for example, in a processor that does not checkpoint).

Parameters:

context - the context to retrieve the CheckpointTrigger from

Returns:

an Optional holding the CheckpointTrigger keyed under RESOURCE_KEY, if present

requestCheckpoint

default void requestCheckpoint()

Requests a checkpoint covering everything handed to the handler so far (the segment's current lastConsumedToken).

Equivalent to requestCheckpoint(TrackingToken.LATEST).

requestCheckpoint

void requestCheckpoint(TrackingToken token)

Requests a checkpoint that must cover at least token: the component declares it is safe up to token. Concurrent requests combine via TrackingToken.upperBound(TrackingToken), so the requested position is the highest anyone asked for and only rises.

Passing TrackingToken.LATEST declares the component safe up to the latest position handed to the handler so far; the owning processor resolves it to that position (it is not the end of the stream). This is equivalent to requestCheckpoint() and is convenient for a component that triggers checkpoints on certain key events without tracking a concrete token.

Parameters:

token - the position the requesting component has made durable, or TrackingToken.LATEST for the latest position handed to the handler so far