Package org.axonframework.messaging.eventhandling.deadletter

Class DeadLetterQueueConfiguration

java.lang.Object
org.axonframework.messaging.eventhandling.deadletter.DeadLetterQueueConfiguration
All Implemented Interfaces:
DescribableComponent
public class DeadLetterQueueConfiguration extends Object implements DescribableComponent
Configuration class holding all settings related to Dead Letter Queue (DLQ) functionality.

This class provides a fluent API for configuring the DLQ behavior, including:

  • Whether DLQ is enabled
  • The EnqueuePolicy to decide which events to dead-letter
  • Whether to clear the DLQ on processor reset
  • The maximum size of the sequence identifier cache

The configuration supports natural merging when combined with defaults using the UnaryOperator.andThen() pattern. Each setter only modifies its specific field, allowing processor-specific configurations to override only selected defaults.

Example usage: 


 config.deadLetterQueue(dlq -> dlq
     .enabled()
     .enqueuePolicy((letter, cause) -> Decisions.enqueue(cause))
     .clearOnReset(false)
     .cacheMaxSize(2048)
 )
Since:
5.1.0
Author:
Mateusz Nowak
See Also:

  • Field Details

    • DEFAULT_ENQUEUE_POLICY

      public static final EnqueuePolicy<EventMessage> DEFAULT_ENQUEUE_POLICY
      The default enqueue policy that always enqueues with a truncated cause message.

  • Constructor Details

    • DeadLetterQueueConfiguration

      public DeadLetterQueueConfiguration()
      Creates a new DeadLetterQueueConfiguration with default settings.

      By default:

      • DLQ is disabled
      • Enqueue policy always enqueues with truncated cause
      • Clear on reset is enabled
      • Cache max size is SequenceIdentifierCache.DEFAULT_MAX_SIZE
      • Factory creates InMemorySequencedDeadLetterQueue instances

  • Method Details

    • enabled

      public DeadLetterQueueConfiguration enabled()
      Enables dead-letter queue functionality for this processor.

      When enabled, failed events will be stored in a dead-letter queue for later processing. The actual queue implementation is provided by a ComponentFactory registered with the configuration.

      Returns:
      This configuration instance for fluent chaining.
      See Also:

    • disabled

      public DeadLetterQueueConfiguration disabled()
      Disables dead-letter queue functionality for this processor.

      This method is useful when DLQ is enabled by default (e.g., via shared defaults) but needs to be disabled for a specific processor.

      Example usage: 

      
 // Enable DLQ for all processors by default
 configurer.eventProcessing(ep -> ep.pooledStreaming(ps -> ps
     .defaults(d -> d.deadLetterQueue(dlq -> dlq.enabled()))
     // But disable for this specific processor
     .processor(EventProcessorModule.pooledStreaming("no-dlq-processor")
         .eventHandlingComponents(...)
         .customized((cfg, c) -> c.deadLetterQueue(dlq -> dlq.disabled())))
 ));
      Returns:
      This configuration instance for fluent chaining.
      See Also:

    • enqueuePolicy

      public DeadLetterQueueConfiguration enqueuePolicy(EnqueuePolicy<EventMessage> enqueuePolicy)
      Sets the EnqueuePolicy to use when deciding whether to dead-letter a failed event.

      The policy is invoked for each failed event and can decide whether to enqueue it in the dead-letter queue, and with what diagnostics information.

      Defaults to a policy that always enqueues with the cause message truncated to 1024 characters.

      Parameters:
      enqueuePolicy - The EnqueuePolicy to use.
      Returns:
      This configuration instance for fluent chaining.

    • clearOnReset

      public DeadLetterQueueConfiguration clearOnReset(boolean clearOnReset)
      Sets whether to clear the dead-letter queue when the processor is reset.

      When true (the default), the dead-letter queue will be cleared when a processor reset is triggered. This ensures that dead-lettered events from before the reset are not processed again.

      Set to false if you want to preserve dead-lettered events across resets.

      Parameters:
      clearOnReset - Whether to clear the DLQ on reset.
      Returns:
      This configuration instance for fluent chaining.

    • cacheMaxSize

      public DeadLetterQueueConfiguration cacheMaxSize(int cacheMaxSize)
      Sets the maximum size of the sequence identifier cache used by the CachingSequencedDeadLetterQueue.

      The cache stores which sequence identifiers are known to be enqueued or not enqueued, avoiding expensive delegate calls. When the cache exceeds this size, oldest entries are evicted using LRU policy.

      Setting this to 0 disables the caching wrapper entirely — the underlying SequencedDeadLetterQueue will be used directly.

      Defaults to SequenceIdentifierCache.DEFAULT_MAX_SIZE (1024).

      Parameters:
      cacheMaxSize - The maximum number of non-enqueued identifiers to cache, or 0 to disable caching.
      Returns:
      This configuration instance for fluent chaining.

    • factory

      public DeadLetterQueueConfiguration factory(SequencedDeadLetterQueueFactory factory)
      Sets the SequencedDeadLetterQueueFactory used to create SequencedDeadLetterQueue instances.

      The factory receives a component-scoped processing group identifier that uniquely identifies the dead letter queue within its event processor. A single processor may contain multiple event handling components, each with its own DLQ. The name follows the pattern "DeadLetterQueue[processorName][componentName]", for example "DeadLetterQueue[myProcessor][myComponent]" for a component named "myComponent" within a processor named "myProcessor".

      This allows using different DLQ implementations such as JPA or JDBC-backed queues instead of the default in-memory implementation.

      Defaults to a factory that creates InMemorySequencedDeadLetterQueue instances.

      Parameters:
      factory - The SequencedDeadLetterQueueFactory that creates a SequencedDeadLetterQueue for a given processing group, e.g. "DeadLetterQueue[myProcessor][0]".
      Returns:
      This configuration instance for fluent chaining.

    • enqueuePolicy

      public EnqueuePolicy<EventMessage> enqueuePolicy()
      Returns the configured EnqueuePolicy.
      Returns:
      The enqueue policy.

    • clearOnReset

      public boolean clearOnReset()
      Returns whether to clear the dead-letter queue on reset.
      Returns:
      true if the queue should be cleared on reset, false otherwise.

    • cacheMaxSize

      public int cacheMaxSize()
      Returns the maximum size of the sequence identifier cache.
      Returns:
      The cache max size.

    • factory

      public SequencedDeadLetterQueueFactory factory()
      Returns the SequencedDeadLetterQueueFactory used to create SequencedDeadLetterQueue instances.
      Returns:
      The SequencedDeadLetterQueueFactory.

    • isEnabled

      public boolean isEnabled()
      Checks if the DLQ is enabled.
      Returns:
      true if DLQ is enabled, false otherwise.

    • describeTo

      public void describeTo(ComponentDescriptor descriptor)
      Description copied from interface: DescribableComponent
      Describe the properties of this DescribableComponent with the given descriptor.

      Components should call the appropriate describeProperty methods on the descriptor to register their properties. The descriptor is responsible for determining how these properties are formatted and structured in the final output.

      Best Practices: As a general rule, all relevant fields of a DescribableComponent implementation should be described in this method. However, developers have discretion to include only the fields that make sense in the context. Not every field may be meaningful for description purposes, especially internal implementation details. Furthermore, components might want to expose different information based on their current state. The final decision on what properties to include lies with the person implementing the describeTo method, who should focus on providing information that is useful for understanding the component's configuration and state.

      Example implementation: 

       public void describeTo(ComponentDescriptor descriptor) {
     descriptor.describeProperty("name", this.name);
     descriptor.describeProperty("enabled", this.enabled);
     descriptor.describeProperty("configuration", this.configuration); // A nested component
     descriptor.describeProperty("handlers", this.eventHandlers);      // A collection
 }
      Specified by:
      describeTo in interface DescribableComponent
      Parameters:
      descriptor - The component descriptor to describe this DescribableComponentn its properties in.