Show TOC

Procedure documentationHandling Dead Messages Locate this document in the navigation structure

 

A dead message for a destination and a consumer is a message that has not been successfully delivered to the consumer registered to this destination for the configured maximum number of attempts. For a topic, a message can be dead for some consumers and deliverable for other consumers.

In the previous version of SAP NetWeaver, the Dead Messages functionality was supported only for queues. Now it is available for topics as well.

To customize the handling of dead messages, you can use the error destination property of your destination.

Syntax Syntax

  1. <property>
	<description>Error Destination</description>
	<config-property-name>errorDestination</config-property-name>
	<config-property-value>MyErrorDestination</config-property-value>
</property>
End of the code.

If it is not configured, the JMS Provider sets up a default error destination for the queue called sapDefaultErrorQueue.

Note Note

You can configure a topic as an error destination, but this may lead to the dead messages being lost in case no active subscriber is registered to the error topic.

End of the note.

When a message for this destination becomes dead, it is simply moved to its error destination. The error destination is a normal JMS destination and does not differ in any way from the ordinary destinations.

If the messages are already in the error destination, you can get information about these messages using the following properties. These properties are automatically inserted in the header of a message when it becomes dead.

  • JMSX_SAP_DEAD_DST_ID - the key for the String property showing the ID of the original destination where this message became dead

  • JMSX_SAP_DEAD_MSG_ID - the key for the Integer property showing the ID of the message, which became dead

  • JMSX_SAP_DEAD_MSG_TIMESTAMP - the key for the long property showing the timestamp of the dead message

  • JMSX_SAP_DEAD_MSG_EXPIRATION - the key for the long property showing the dead message's expiration timestamp

  • JMSX_SAP_DEAD_MSG_CORRELATIONID - the key for the String property showing the dead message correlation ID

  • JMSX_SAP_DEAD_MSG_CONNECTIONID - the key for the long property showing the connection ID for the dead message consumer

For example, to get the dead message's expiration timestamp you have to use getLongProperty(JMSX_SAP_DEAD_MSG_TIMESTAMP, Long).

Procedure

You have to configure the following properties in the jms-resources.xml related to the dead messages functionality.

  • deliveryAttemptsLimited - a Boolean property that indicates whether the message delivery attempts are limited. The default value is "true".

  • maxDeliveryAttempts - an Integer property that indicates the maximum number of delivery attempts before the message is considered undeliverable (dead). The default value is 5.

  • deliveryDelayInterval - the delay in milliseconds between two consecutive message delivery attempts. The default value of this property is 2000 milliseconds and it is configurable for every destination.

  • errorDestination - the name of a JMS destination where dead messages will be moved. A particular value " " of this property is reserved to denote the null destination, which is interpreted as a token to drop dead messages instead of moving them to an error destination.

    Note Note

    The default error destination has an empty string for the errorDestination property, otherwise, when a message becomes dead for the error destination, this may lead to several transfers of this message through error destinations and potentially even lead to a delivery cycle. The property value of an error destination must be the name of an already existing Queue or Topic.

    End of the note.

Syntax Syntax

  1. <?xml version="1.0" encoding="UTF-8"?>
<jms-resources xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="jms-resources.xsd">
	<application-name>MyApplication</application-name>
	<connection-factory>
		<name>MyQueueFactory</name>
		<sap-local-factory-type>
			<type>javax.jms.QueueConnectionFactory</type>
			<virtual-provider>default</virtual-provider>
			<property>
				<description>Client ID</description>
				<config-property-name>clientID</config-property-name>
				<config-property-value>
					myClientApp
				</config-property-value>
			</property>
		</sap-local-factory-type>
	</connection-factory>
	<destination>
		<name>MyQueue</name>
		<type>javax.jms.Queue</type>
		<sap-local-destination-type>
			<virtual-provider>default</virtual-provider>
			<property>
				<description>
					Message Delivery Attempts Limited
				</description>
				<config-property-name>
					deliveryAttemptsLimited
				</config-property-name>
				<config-property-value>true</config-property-value>
			</property>
			<property>
				<description>Maximum Delivery Attempts</description>
				<config-property-name>
					maxDeliveryAttempts
				</config-property-name>
				<config-property-value>30</config-property-value>
			</property>
			<property>
				<description>Delay in Milliseconds</description>
				<config-property-name>
					deliveryDelayInterval
				</config-property-name>
				<config-property-value>60000</config-property-value>
			</property>
			<property>
				<description>Error Destination</description>
				<config-property-name>
					errorDestination
				</config-property-name>
				<config-property-value>
					MyErrorDestination
				</config-property-value>
			</property>
		</sap-local-destination-type>
	</destination>

</jms-resources>
End of the code.