Sun Java System Message Queue 4.3 Developer's Guide for C 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. 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 Sun Java System Message Queue 4.3 Administration Guide.

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

(Message Queue 4.3 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.3 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 Sun Java System Message Queue 4.3 Developer’s Guide for Java Clients. or the JMX API, described in Sun Java System Message Queue 4.3 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.