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. For a description of the destination properties and of the broker properties that control the system’s use of the dead message queue, see Using the Dead Message Queue in Oracle GlassFish Server Message Queue 4.5 Administration Guide.

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

Whether a dead message can be sent to the dead message queue.
Whether the broker should log information when a message is destroyed or moved to the dead message queue.
Whether the body of the message should also be stored when the message is placed on the dead message queue.
Why the message was placed on the dead message queue and any ancillary information.

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

The dead message queue is automatically created by the system and called mq.sys.dmq. You can write a Java program that uses the metrics monitoring API, described in Chapter 4, Using the Metrics Monitoring API, in Oracle GlassFish Server Message Queue 4.5 Developer’s Guide for Java Clients. or the JMX API, described in Oracle GlassFish Server Message Queue 4.5 Developer’s Guide for JMX Clients, 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-3 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 default destination, or default broker-based behavior.

Table 3-3 Message Properties Relating to Dead Message Queue

Property	Type	Description
`JMS_SUN_PRESERVE_UNDELIVERED`	Boolean	For a dead message, 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`	Boolean	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`	Boolean	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-4 are set by the client runtime for a message placed in the dead message queue.

Table 3-4 Dead Message Properties

Property	Type	Description
`JMSXDeliveryCount`	Integer	Specifies 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`	Long	Specifies the time (in milliseconds) when the message was placed on the dead message queue.
`JMS_SUN_DMQ_UNDELIVERED_REASON`	String	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` value is returned when a message cannot be delivered due to an internal error; this is an unusual condition. In this case, the sender should just resend the message.
`JMS_SUN_DMQ_PRODUCING_BROKER`	String	For message traffic in broker clusters: specifies the name and port number of the broker that sent the message. A null value indicates that it was the local broker.
`JMS_SUN_DMQ_DEAD_BROKER`	String	For message traffic in broker clusters: specifies the name and port number of the broker that placed the message on the dead message queue. A null value indicates that it was the local broker.
`JMS_SUN_DMQ_UNDELIVERED_EXCEPTION`	String	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_COMMENTS`	String	An optional comment provided when the message is marked dead.
`JMS_SUN_DMQ_BODY_TRUNCATED`	Boolean	A value of `true` indicates that the message body was not stored. A value of `false` indicates that the message body was stored.

Skip Navigation Links
Exit Print View
	Oracle GlassFish Server Message Queue 4.5 Developer's Guide for C Clients