Package io.axoniq.framework.messaging.eventhandling.deadletter

Class DeadLetteringEventHandlingComponent

java.lang.Object

org.axonframework.messaging.eventhandling.DelegatingEventHandlingComponent

io.axoniq.framework.messaging.eventhandling.deadletter.DeadLetteringEventHandlingComponent

All Implemented Interfaces:

SequencedDeadLetterProcessor<EventMessage>, DescribableComponent, MessageHandler, EventHandler, EventHandlingComponent, ReplayStatusChangedHandler, ResetHandler

public class DeadLetteringEventHandlingComponent
extends DelegatingEventHandlingComponent
implements SequencedDeadLetterProcessor<EventMessage>

An EventHandlingComponent decorator that uses a SequencedDeadLetterQueue to enqueue events for which handling failed.

Uses an EnqueuePolicy to decide whether a failed event should be enqueued. Subsequent events belonging to an already enqueued "sequence identifier" are also enqueued to maintain event ordering in the face of failures.

Replayed events are treated differently when their sequence already holds dead letters. Replayed events positioned before the head of the sequence are handled by the delegate, since they may rebuild state the head letter depends on. Replayed events already present in the sequence are skipped, and a replayed event that fails is enqueued in position order instead of at the tail. Placing letters in position order touches every later letter of the sequence, so it is strongly recommended to resolve enqueued dead letters, by processing or evicting them, before replaying.

This component provides operations to processAny() dead letters it has enqueued through the SequencedDeadLetterProcessor contract. It ensures the same delegate EventHandlingComponent is used when processing dead letters as with regular event handling. Each dead letter is processed in its own UnitOfWork, providing proper transaction boundaries.

Since:

4.6.0

Author:

Steven van Beelen, Mitchell Herrijgers, Mateusz Nowak

See Also:

• SequencedDeadLetterQueue
• SequencedDeadLetterProcessor
• EnqueuePolicy

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DECORATION_ORDER	The order for decorating EventHandlingComponents with dead-lettering support.

Fields inherited from class org.axonframework.messaging.eventhandling.DelegatingEventHandlingComponent

delegate

Constructor Summary

Constructors

Constructor	Description
DeadLetteringEventHandlingComponent(EventHandlingComponent delegate, SequencedDeadLetterQueue<EventMessage> queue, EnqueuePolicy<EventMessage> enqueuePolicy, UnitOfWorkFactory unitOfWorkFactory, boolean allowReset)	Instantiate a DeadLetteringEventHandlingComponent with the given delegate, queue, custom EnqueuePolicy, reset behavior, and unitOfWorkFactory.

Method Summary

Modifier and Type	Method	Description
MessageStream.Empty<Message>	handle(EventMessage event, ProcessingContext context)	Handles the given event within the given context.
MessageStream.Empty<Message>	handle(ResetContext resetContext, ProcessingContext context)	Handles the given ResetContext message, performing any necessary reset operations.
CompletableFuture<Boolean>	process(Predicate<DeadLetter<? extends EventMessage>> sequenceFilter)	Process a sequence of dead letters matching the given sequenceFilter.
CompletableFuture<Boolean>	process(Predicate<DeadLetter<? extends EventMessage>> sequenceFilter, @Nullable ProcessingContext context)	Process a sequence of dead letters matching the given sequenceFilter.
CompletableFuture<Boolean>	processAny()	Process any sequence of dead letters belonging to this component.
CompletableFuture<Boolean>	processAny(@Nullable ProcessingContext context)	Process any sequence of dead letters belonging to this component in the given context.

Methods inherited from class org.axonframework.messaging.eventhandling.DelegatingEventHandlingComponent

describeTo, handle, sequenceIdentifierFor, supportedEvents, supports, supportsReset, unwrap

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DECORATION_ORDER

public static final int DECORATION_ORDER

The order for decorating EventHandlingComponents with dead-lettering support.

This order is applied after interceptors to ensure dead-lettering wraps the fully decorated component.

See Also:

• Constant Field Values

Constructor Details

DeadLetteringEventHandlingComponent

public DeadLetteringEventHandlingComponent(EventHandlingComponent delegate,
 SequencedDeadLetterQueue<EventMessage> queue,
 EnqueuePolicy<EventMessage> enqueuePolicy,
 UnitOfWorkFactory unitOfWorkFactory,
 boolean allowReset)

Instantiate a DeadLetteringEventHandlingComponent with the given delegate, queue, custom EnqueuePolicy, reset behavior, and unitOfWorkFactory.

Parameters:

delegate - the EventHandlingComponent to delegate event handling to

queue - the SequencedDeadLetterQueue to store dead letters in

enqueuePolicy - the EnqueuePolicy to decide whether a failed event should be dead-lettered

unitOfWorkFactory - the UnitOfWorkFactory to create UnitOfWork instances for processing dead letters

allowReset - whether to clear the queue on reset. If true, SequencedDeadLetterQueue.clear(ProcessingContext) will be invoked upon a reset

Method Details

handle

public MessageStream.Empty<Message> handle(EventMessage event,
 ProcessingContext context)

Description copied from interface: EventHandler

Handles the given event within the given context.

The result of handling is an empty stream.

Specified by:

handle in interface EventHandler

Overrides:

handle in class DelegatingEventHandlingComponent

Parameters:

event - The event to handle.

context - The context to the given event is handled in.

Returns:

An empty stream containing nothing.

handle

public MessageStream.Empty<Message> handle(ResetContext resetContext,
 ProcessingContext context)

Description copied from interface: ResetHandler

Handles the given ResetContext message, performing any necessary reset operations.

This method is invoked before the processor begins replaying events. Handlers typically use this opportunity to clean up state that will be rebuilt during replay.

If this method completes exceptionally, the reset operation will be aborted and no replay will occur.

Specified by:

handle in interface EventHandlingComponent

Specified by:

handle in interface ResetHandler

Overrides:

handle in class DelegatingEventHandlingComponent

Parameters:

resetContext - The reset context message containing reset information and optional payload.

context - The processing context for this operation.

Returns:

An empty message stream after handling completes successfully.

process

public CompletableFuture<Boolean> process(Predicate<DeadLetter<? extends EventMessage>> sequenceFilter)

Description copied from interface: SequencedDeadLetterProcessor

Process a sequence of dead letters matching the given sequenceFilter.

Note that only a single matching sequence is processed! Furthermore, the sequenceFilter is only invoked for the first letter of a sequence, as the first entry blocks the entire sequence.

Each dead letter is processed in its own processing context (typically a UnitOfWork), which will have the DeadLetter added as a resource (via DeadLetter.RESOURCE_KEY). The message from the dead letter is also added to the context via Message.RESOURCE_KEY.

Specified by:

process in interface SequencedDeadLetterProcessor<EventMessage>

Parameters:

sequenceFilter - a filter for the first dead letter entries of each sequence

Returns:

a CompletableFuture with true if at least one dead letter was processed successfully, false otherwise

process

public CompletableFuture<Boolean> process(Predicate<DeadLetter<? extends EventMessage>> sequenceFilter,
 @Nullable ProcessingContext context)

Description copied from interface: SequencedDeadLetterProcessor

Process a sequence of dead letters matching the given sequenceFilter.

The context can be provided optionally to support effective resource management down stream in the SequencedDeadLetterQueue and dead-letter processing task.

Specified by:

process in interface SequencedDeadLetterProcessor<EventMessage>

Parameters:

sequenceFilter - a filter for the first dead letter entries of each sequence

context - the processing context in which to process the dead letters, if any

Returns:

a CompletableFuture with true if at least one dead letter was processed successfully, false otherwise

processAny

public CompletableFuture<Boolean> processAny()

Description copied from interface: SequencedDeadLetterProcessor

Process any sequence of dead letters belonging to this component.

Note that only a single matching sequence is processed!

Each dead letter is processed in its own processing context (typically a UnitOfWork), which will have the DeadLetter added as a resource (via DeadLetter.RESOURCE_KEY). The message from the dead letter is also added to the context via Message.RESOURCE_KEY.

Specified by:

processAny in interface SequencedDeadLetterProcessor<EventMessage>

Returns:

a CompletableFuture with true if at least one dead letter was processed successfully, false otherwise

processAny

public CompletableFuture<Boolean> processAny(@Nullable ProcessingContext context)

Description copied from interface: SequencedDeadLetterProcessor

Process any sequence of dead letters belonging to this component in the given context.

The context can be provided optionally to support effective resource management down stream in the SequencedDeadLetterQueue and dead-letter processing task.

Specified by:

processAny in interface SequencedDeadLetterProcessor<EventMessage>

Parameters:

context - the processing context in which to process the dead letters, if any

Returns:

a CompletableFuture with true if at least one dead letter was processed successfully, false otherwise