Sun GlassFish Message Queue 4.4 Developer's Guide for Java Clients

Managing the Dead Message Queue

When a message is deemed undeliverable, it is automatically placed on a special queue called the dead message queue. A message placed on this queue retains all of its original headers (including its original destination) and information is added to the message’s properties to explain why it became a dead message. An administrator or a developer can access this queue, remove a message, and determine why it was placed on the queue.

This section describes the message properties that you can set or examine programmatically to determine the following:

Message Queue 3.6 clients can set properties related to the dead message queue on messages and send those messages to clients compiled against earlier versions. However clients receiving such messages cannot examine these properties without recompiling against 3.6 libraries.

The dead message queue is automatically created by the broker and called mq.sys.dmq. You can use the message monitoring API, described in Chapter 4, Using the Metrics Monitoring API, to determine whether that queue is growing, to examine messages on that queue, and so on.

You can set the properties described in Table 3–2 for any message to control how the broker should handle that message if it deems it to be undeliverable. Note that these message properties are needed only to override destination, or broker-based behavior.

Table 3–2 Message Properties Relating to Dead Message Queue

Property 

Description 

JMS_SUN_PRESERVE_UNDELIVERED

A boolean whose value determines what the broker should do with the message if it is dead.  

The default value of unset, specifies that the message should be handled as specified by the useDMQ property of the destination to which the message was sent.

A value of true overrides the setting of the useDMQ property and sends the dead message to the dead message queue.

A value of false overrides the setting of the useDMQ property and prevents the dead message from being placed in the dead message queue.

JMS_SUN_LOG_DEAD_MESSAGES

A boolean value that determines how activity relating to dead messages should be logged. 

The default value of unset, will behave as specified by the broker configuration property imq.destination.logDeadMsgs.

A value of true overrides the setting of the imq.destination.logDeadMsgs broker property and specifies that the broker should log the action of removing a message or moving it to the dead message queue.

A value of false overrides the setting of the imq.destination.logDeadMsgs broker property and specifies that the broker should not log these actions.

JMS_SUN_TRUNCATE_MSG_BODY

A boolean value that specifies whether the body of a dead message is truncated. 

The default value of unset, will behave as specified by the broker property imq.destination.DMQ.truncateBody.

A value of true overrides the setting of the imq.destination.DMQ.truncateBody property and specifies that the body of the message should be discarded when the message is placed in the dead message queue.

A value of false overrides the setting of the imq.destination.DMQ.truncateBody property and specifies that the body of the message should be stored along with the message header and properties when the message is placed in the dead message queue.

The properties described in Table 3–3 are set by the broker for a message placed in the dead message queue. You can examine the properties for the message to retrieve information about why the message was placed on the queue and to gather other information about the message and about the context within which this action was taken.

Table 3–3 Dead Message Properties

Property 

Description 

JMSXDeliveryCount

An Integer that pecifies the most number of times the message was delivered to a given consumer. This value is set only for ERROR or UNDELIVERABLE messages.

JMS_SUN_DMQ_UNDELIVERED_TIMESTAMP

A Long that pecifies the time (in milliseconds) when the message was placed on the dead message queue.

JMS_SUN_DMQ_UNDELIVERED_REASON

A string that specifies one of the following values to indicate the reason why the message was placed on the dead message queue:

OLDEST

LOW_PRIORITY

EXPIRED

UNDELIVERABLE

ERROR

If the message was marked dead for multiple reasons, for example it was undeliverable and expired, only one reason will be specified by this property. 

The ERROR reason indicates that an internal error made it impossible to process the message. This is an extremely unusual condition, and the sender should just resend the message.

JMS_SUN_DMQ_PRODUCING_BROKER

A String used for message traffic in broker clusters: it specifies the broker name and port number of the broker that produced the message. A null value indicates the local broker.

JMS_SUN_DMQ_DEAD_BROKER

A String used for message traffic in broker clusters: it specifies the broker name and port number of the broker that placed the message on the dead message queue. A null value indicates the local broker.

JMS_SUN_DMQ_UNDELIVERED_EXCEPTION

A String that specifies the name of the exception (if the message was dead because of an exception) on either the client or the broker.

JMS_SUN_DMQ_UNDELIVERED_COMMENT

A String used to provide an optional comment when the message is marked dead.

JMS_SUN_DMQ_BODY_TRUNCATED

A Boolean: a value of true indicates that the message body was not stored. A value of false indicates that the message body was stored.