Package dev.agenor.core.deadletter

Record Class DeadLetter

java.lang.Object
java.lang.Record
dev.agenor.core.deadletter.DeadLetter
Record Components:
message - the message that was given up on; never null
reason - why it was given up on, in a form a human reads; never null
recipientId - the agent the message was addressed to, or null for a topic delivery, where no single agent was the intended recipient
attempts - how many times a handler was invoked for this message; at least 1
deadLetteredAt - when the framework gave up
public record DeadLetter(Message message, String reason, String recipientId, int attempts, Instant deadLetteredAt) extends Record
A message the framework has stopped trying to deliver, and why.

A dead letter is a record of a decision already taken: the message is not queued for another attempt, and recording it changes nothing about its fate. It exists so that the fate is legible — before this type, a message lost on the in-memory transport left one log line, and one dead-lettered on Redis left an entry in a stream no API could read.

attempts counts how many times a handler was actually invoked for this message. On a transport with redelivery it is the exhausted attempt limit; on one without, it is 1. That is a fact about the transport, not a placeholder — a dead letter with one attempt says the message was never retried because retrying it was never possible.

Since:
0.32.0

  • Constructor Details

  • Method Details

    • of

      public static DeadLetter of(Message message, String recipientId, Throwable cause)
      Records a message given up on after a single attempt, which is the only outcome a transport without redelivery can produce.

      The reason is taken from the failure's own message where it has one, and from its type where it does not — an exception with a null message is common enough that "null" would otherwise be the most frequent reason in the queue.

      Parameters:
      message - the message that failed; must not be null
      recipientId - the agent it was addressed to, or null for a topic delivery
      cause - the failure; must not be null
      Returns:
      the dead letter, timestamped now; never null

    • of

      public static DeadLetter of(Message message, String recipientId, Throwable cause, int attempts)
      Records a message given up on after attempts handler invocations.
      Parameters:
      message - the message that failed; must not be null
      recipientId - the agent it was addressed to, or null for a topic delivery
      cause - the failure; must not be null
      attempts - how many times a handler was invoked; at least 1
      Returns:
      the dead letter, timestamped now; never null

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • message

      public Message message()
      Returns the value of the message record component.
      Returns:
      the value of the message record component

    • reason

      public String reason()
      Returns the value of the reason record component.
      Returns:
      the value of the reason record component

    • recipientId

      public String recipientId()
      Returns the value of the recipientId record component.
      Returns:
      the value of the recipientId record component

    • attempts

      public int attempts()
      Returns the value of the attempts record component.
      Returns:
      the value of the attempts record component

    • deadLetteredAt

      public Instant deadLetteredAt()
      Returns the value of the deadLetteredAt record component.
      Returns:
      the value of the deadLetteredAt record component