| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <html> |
| <head> |
| <title>ActiveMQ Artemis Dead Letter Example</title> |
| <link rel="stylesheet" type="text/css" href="../../../common/common.css" /> |
| <link rel="stylesheet" type="text/css" href="../../../common/prettify.css" /> |
| <script type="text/javascript" src="../../../common/prettify.js"></script> |
| </head> |
| <body onload="prettyPrint()"> |
| <h1>Dead Letter Example</h1> |
| <pre>To run the example, simply type <b>mvn verify</b> from this directory, <br>or <b>mvn -PnoServer verify</b> if you want to start and create the server manually.</pre> |
| |
| <p>This example shows you how to define and deal with dead letter messages.</p> |
| <p>Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume them is rolled back). |
| Such a message goes back to the JMS destination ready to be redelivered. |
| However, this means it is possible for a message to be delivered again and again without any success and remain in the destination, clogging the system.</p> |
| <p>To prevent this, messaging systems define dead letter messages: after a specified unsuccessful delivery attempts, the message is removed from the destination |
| and instead routed to a <em>dead letter address</em> where they can be consumed for further investigation. |
| <p> |
| The example will show how to configure ActiveMQ Artemis to route a message to a dead letter address after 3 unsuccessful delivery attempts.<br /> |
| The example will send 1 message to a queue. We will deliver the message 3 times and rollback the session every time.<br /> |
| On the 4th attempt, there won't be any message to consume: it will have been moved to a <em>dead letter address</em>.<br /> |
| We will then consume this dead letter message. |
| </p> |
| <h2>Example setup</h2> |
| <p><em>Dead letter addresses</em> and <em>maximum delivery attempts</em> are defined in the configuration file <a href="src/main/resources/activemq/server0/broker.xml">broker.xml</a>:</p> |
| <pre class="prettyprint"> |
| <code><address-setting match="jms.queue.exampleQueue"> |
| <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address> |
| <max-delivery-attempts>3</max-delivery-attempts> |
| </address-setting> |
| </code> |
| </pre> |
| <p>This configuration will moved dead letter messages from <code>exampleQueue</code> to the <code>deadLetterQueue</code>.</p> |
| <p>ActiveMQ Artemis allows to specify either a <code>Queue</code> by prefixing the <code>dead-letter-address</code> with <code>jms.queue.</code> |
| or a <code>Topic</code> by prefixing with <code>jms.topic.</code>.<br /> |
| In this example, we will use a <code>Queue</code> to hold the dead letter messages.</p> |
| <p>The maximum attempts of delivery is <code>3</code>. Once this figure is reached, a message is considered a dead letter message and is moved to |
| the <code>deadLetterQueue</code>. |
| <p>Since we want to consume messages from this deadLetterQueue, we also need to add a JNDI binding to perform a lookup. |
| This is configured in <a href="src/main/resources/activemq/server0/activemq-jms.xml">activemq-jms.xml</a></p> |
| <pre class="prettyprint"> |
| <code><queue name="deadLetterQueue"> |
| <entry name="/queue/deadLetterQueue"/> |
| </queue></code> |
| </pre> |
| </body> |
| </html> |
