Poison messages

A poison message is a message that a receiving application cannot process. You can handle poison messages in your Eclipse Amlen JMS application by using the JMSXDeliveryCount message property.

A poison message might be a corrupted message, or a message in an unexpected format. For example, if an application handles JMS messages of type TextMessage receives a message of a different type, that message is a poison message.

If an application encounters a poison message, it can take one of the following actions:

  • Roll back the message to the topic or queue it came from.

    You can roll back the message if the application is using transactions. Rolling back the message ensures that the message is not lost. It is useful if a message is incorrectly identified as a poison message because the application is unable to process it due to a transient issue.
    Note: If the application is a Message Driven Bean (MDB), the MDB can call the setRollbackOnly() method on the message-driven context that is associated with it.

  • Move the message onto a special queue.

    You might want to move the message to a special queue if the application is not using transactions and you do not want the message to be lost.

  • Discard the message.

    If you discard the message, the message is lost.

It is the responsibility of the application to determine whether a poison message is received. Eclipse Amlen cannot detect that a message is corrupted and does not know whether an application expects to receive a specific JMS message type.

Handling poison messages by using JMSXDeliveryCount

You can use the JMSXDeliveryCount message property to detect situations where a poison message is being continually received and rolled back. The JMSXDeliveryCount message property provides a count value for the number of times that a particular message is delivered. You can use this property in your application to identify poison messages by establishing a threshold value for the delivery count. When the threshold is reached, you can provide alternative handling for the message. For example, you can send the message to a special queue for failed messages, or you can discard the message.

To use the JMSXDeliveryCount property, configure your application to call the getIntProperty() method on the message:
int deliveryCount = message.getIntProperty("JMSXDeliveryCount");
The maximum value for the JMSXDeliveryCount property in Eclipse Amlen is 64. Therefore, you must set your delivery count threshold value to 64 or less when you write your application.

Considerations for MDB applications that use the Eclipse Amlen resource adapter

In some cases, unexpected transient issues, such as a database outage, can lead to valid messages not being processed. To avoid incorrectly identifying messages as poison messages, you can set the maxDeliveryFailures property on the activation specification. The maxDeliveryFailures property pauses the MDB after the set number of failures is reached. Pausing the MDB gives the administrator time to address the issues that are preventing successful message processing.

When the destination is a queue or when a durable subscription is used, the MDB must be restarted promptly after a pause. If the MDB is not restarted after a pause, a backlog of messages can accumulate.

For more information about the maxDeliveryFailures property, see Configuring the Eclipse Amlen resource adapter for inbound communication.