[jboss-cvs] JBoss Messaging SVN: r6281 - in trunk: examples/jms and 9 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Apr 2 12:09:55 EDT 2009
Author: jmesnil
Date: 2009-04-02 12:09:55 -0400 (Thu, 02 Apr 2009)
New Revision: 6281
Added:
trunk/examples/jms/dead-letter/
trunk/examples/jms/dead-letter/build.xml
trunk/examples/jms/dead-letter/readme.html
trunk/examples/jms/dead-letter/src/
trunk/examples/jms/dead-letter/src/org/
trunk/examples/jms/dead-letter/src/org/jboss/
trunk/examples/jms/dead-letter/src/org/jboss/jms/
trunk/examples/jms/dead-letter/src/org/jboss/jms/example/
trunk/examples/jms/dead-letter/src/org/jboss/jms/example/DeadLetterExample.java
Modified:
trunk/.classpath
trunk/examples/jms/common/config/jbm-jms.xml
trunk/examples/jms/common/config/jbm-queues.xml
trunk/src/main/org/jboss/messaging/core/deployers/impl/AddressSettingsDeployer.java
trunk/src/schemas/jbm-queues.xsd
Log:
JMS Dead Letter example
+ added missing max-delivery-attempts setting from AddressSettingsDeployer
Modified: trunk/.classpath
===================================================================
--- trunk/.classpath 2009-04-02 15:17:42 UTC (rev 6280)
+++ trunk/.classpath 2009-04-02 16:09:55 UTC (rev 6281)
@@ -15,6 +15,7 @@
<classpathentry kind="src" path="tests/joram-tests/config"/>
<classpathentry kind="src" path="examples/jms/browser/src"/>
<classpathentry kind="src" path="examples/jms/common/src"/>
+ <classpathentry kind="src" path="examples/jms/dead-letter/src"/>
<classpathentry kind="src" path="examples/jms/durable/src"/>
<classpathentry kind="src" path="examples/jms/expiry/src"/>
<classpathentry kind="src" path="examples/jms/paging/src"/>
Modified: trunk/examples/jms/common/config/jbm-jms.xml
===================================================================
--- trunk/examples/jms/common/config/jbm-jms.xml 2009-04-02 15:17:42 UTC (rev 6280)
+++ trunk/examples/jms/common/config/jbm-jms.xml 2009-04-02 16:09:55 UTC (rev 6281)
@@ -18,6 +18,10 @@
<entry name="/queue/expiryQueue"/>
</queue>
+ <queue name="deadLetterQueue">
+ <entry name="/queue/deadLetterQueue"/>
+ </queue>
+
<topic name="topic">
<entry name="/topic/exampleTopic"/>
</topic>
Modified: trunk/examples/jms/common/config/jbm-queues.xml
===================================================================
--- trunk/examples/jms/common/config/jbm-queues.xml 2009-04-02 15:17:42 UTC (rev 6280)
+++ trunk/examples/jms/common/config/jbm-queues.xml 2009-04-02 16:09:55 UTC (rev 6281)
@@ -53,9 +53,10 @@
<!--default for catch all-->
<address-settings match="#">
<clustered>false</clustered>
- <dead-letter-address>queuejms.DLQ</dead-letter-address>
+ <dead-letter-address>queuejms.deadLetterQueue</dead-letter-address>
<expiry-address>queuejms.expiryQueue</expiry-address>
<redelivery-delay>0</redelivery-delay>
+ <max-delivery-attempts>3</max-delivery-attempts>
<max-size-bytes>-1</max-size-bytes>
<page-size-bytes>10485760</page-size-bytes>
<distribution-policy-class>org.jboss.messaging.core.server.impl.RoundRobinDistributor</distribution-policy-class>
Property changes on: trunk/examples/jms/dead-letter
___________________________________________________________________
Name: svn:ignore
+ build
Added: trunk/examples/jms/dead-letter/build.xml
===================================================================
--- trunk/examples/jms/dead-letter/build.xml (rev 0)
+++ trunk/examples/jms/dead-letter/build.xml 2009-04-02 16:09:55 UTC (rev 6281)
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE project [
+ <!ENTITY libraries SYSTEM "../../../thirdparty/libraries.ent">
+ ]>
+
+<!-- =========================================================================================== -->
+<!-- -->
+<!-- JBoss, Home of Professional Open Source -->
+<!-- Copyright 2005, JBoss Inc., and individual contributors as indicated -->
+<!-- by the @authors tag. See the copyright.txt in the distribution for a -->
+<!-- full listing of individual contributors. -->
+<!-- -->
+<!-- This is free software; you can redistribute it and/or modify it -->
+<!-- under the terms of the GNU Lesser General Public License as -->
+<!-- published by the Free Software Foundation; either version 2.1 of -->
+<!-- the License, or (at your option) any later version. -->
+<!-- -->
+<!-- This software is distributed in the hope that it will be useful, -->
+<!-- but WITHOUT ANY WARRANTY; without even the implied warranty of -->
+<!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -->
+<!-- Lesser General Public License for more details. -->
+<!-- -->
+<!-- You should have received a copy of the GNU Lesser General Public -->
+<!-- License along with this software; if not, write to the Free -->
+<!-- Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA -->
+<!-- 02110-1301 USA, or see the FSF site: http://www.fsf.org. -->
+<!-- -->
+<!-- =========================================================================================== -->
+
+
+<project default="run" name="JBoss Messaging Dead Letter Example">
+
+ <import file="../common/build.xml"/>
+
+ <target name="run">
+ <antcall target="runExample">
+ <param name="example.classname" value="org.jboss.jms.example.DeadLetterExample"/>
+ </antcall>
+ </target>
+
+ <target name="runRemote">
+ <antcall target="runExample">
+ <param name="example.classname" value="org.jboss.jms.example.DeadLetterExample"/>
+ <param name="jbm.example.runServer" value="false"/>
+ </antcall>
+ </target>
+
+</project>
\ No newline at end of file
Added: trunk/examples/jms/dead-letter/readme.html
===================================================================
--- trunk/examples/jms/dead-letter/readme.html (rev 0)
+++ trunk/examples/jms/dead-letter/readme.html 2009-04-02 16:09:55 UTC (rev 6281)
@@ -0,0 +1,201 @@
+<html>
+ <head>
+ <title>JBoss Messaging Dead Letter Example</title>
+ <link rel="stylesheet" type="text/css" href="../common/common.css">
+ </head>
+ <body>
+ <h1>Dead Letter Example</h1>
+
+ <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 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 attemps, the message is removed from the destination
+ and put instead in a <em>dead letter destination</em> where they can be consumed for further investigation.
+ <p>
+ The example will show how to configure JBoss Messaging to send a message to a dead letter destination after 3 unsuccesful 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 queue</em>.<br />
+ We will then consume the message from this dead letter queue.
+ </p>
+ <h2>Example setup</h2>
+ <p><em>Dead letter destinations</em> and <em>maximum delivery attempts</em> are defined in the queue settings configuration file <a href="../common/config/jbm-queues.xml">jbm-queues.xml</a>:</p>
+ <pre>
+ <code><!--default for all queues-->
+ <address-settings match="#">
+ ...
+ <dead-letter-address>queuejms.deadLetterQueue</dead-letter-address>
+ ...
+ <max-delivery-attempts>3</max-delivery-attempts>
+ ...
+ </address-settings></code>
+ </pre>
+ <p>This configuration will moved dead letter messages from any given queue (the wildcard <code>#</code>) to the <code>deadLetterQueue</code>.</p>
+ <p>JBoss Messaging allows to specify either a <code>Queue</code> by prefixing the <code>dead-letter-address</code> with <code>queuejms.</code>
+ or a <code>Topic</code> by prefixing with <code>topicjms.</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="../common/config/jbm-jms.xml">jbm-jms.xml</a></p>
+ <pre>
+ <code><queue name="deadLetterQueue">
+ <entry name="/queue/deadLetterQueue"/>
+ </queue></code>
+ </pre>
+ </p>
+ <h2>Example step-by-step</h2>
+ <p><i>To run the example, simply type <code>ant</code> from this directory</i></p>
+ <ol>
+ <li>First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the <code>client-jndi.properties</code> file in the directory <code>../common/config</code></li>
+ <pre>
+ <code>InitialContext initialContext = getContext();</code>
+ </pre>
+
+ <li>We look up the JMS queue object from JNDI</li>
+ <pre>
+ <code>Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");</code>
+ </pre>
+
+ <li>We look up the JMS connection factory object from JNDI</li>
+ <pre>
+ <code>ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");</code>
+ </pre>
+
+ <li>We create a JMS connection</li>
+ <pre>
+ <code>connection = cf.createConnection();</code>
+ </pre>
+
+ <li>We create a JMS <em>transacted</em> session
+ <pre>
+ <code>Session session = connection.createSession(true, 0);</code>
+ </pre>
+
+ <li>We create a JMS message producer on the session. This will be used to send the messages</li>
+ <pre>
+ <code>MessageProducer messageProducer = session.createProducer(topic);</code>
+ </pre>
+
+ <li>We create a text messages</li>
+ <pre>
+ <code>TextMessage message = session.createTextMessage("this is a text message");</code>
+ </pre>
+
+ <li>We send the message to the queue</li>
+ <pre>
+ <code>producer.send(message);</code>
+ </pre>
+
+ <li>We commit the session to effectively send the message to the queue</li>
+ <pre>
+ <code>session.commit();</code>
+ </pre>
+
+ <p>We will now consume the message from the queue 3 times and roll back the session every time</p>
+
+ <li>We create a JMS message consumer on the queue</li>
+ <pre>
+ <code>MessageConsumer messageConsumer = session.createConsumer(queue);</code>
+ </pre>
+
+ <li>We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started</li>
+ <pre>
+ <code>connection.start();</code>
+ </pre>
+
+ <li>We receive the message a 1<sup>st</sup> time</li>
+ <pre>
+ <code>TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("1st delivery from " + queue.getQueueName() + ": " + messageReceived.getText());</code>
+ </pre>
+
+ <li>We roll back the session. The message we received is undelivered and goes back to the queue</li>
+ <pre>
+ <code>session.rollback();</code>
+ </pre>
+
+ <li>We receive a message and roll back the session a 2<sup>nd</sup> time
+ <pre>
+ <code>messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("2nd delivery from " + queue.getQueueName() + ": " + messageReceived.getText());
+ session.rollback();</code>
+ </pre>
+
+ <li>We do it againt a 3<sup>rd</sup> time
+ <pre>
+ <code>messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("3rd delivery from " + queue.getQueueName() + ": " + messageReceived.getText());
+ session.rollback();</code>
+ </pre>
+
+ <p>Since the queue was configured to move messages to the <code>deadLetterQueue</code> after <code>3</code> unsuccessful delivery attempts,
+ the message won't be in the <code>queue</code> anymore</p>
+
+ <li>We try to receive a message from the queue for a 4<sup>th</sup>. Since there is none, the call will timeout after 5000ms and <code>messageReceived</code> will be <code>null</code>
+ <pre>
+ <code>messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("4th delivery from " + queue.getQueueName() + ": " + messageReceived);</code>
+ </pre>
+
+ <p>We have configured JBoss Messaging to send any dead letter messages to the <code>deadLetterQueue</code>.
+ We will now consume messages from this queue and receives the <em>dead letter messages</em>.</p>
+
+ <li>We look up the JMS <em>dead letter queue</em> object from JNDI</li>
+ <pre>
+ <code>Queue deadLetterQueue = (Queue)initialContext.lookup("/queue/deadLetterQueue");</code>
+ </pre>
+
+ <li>We create a JMS message consumer on the dead letter queue</li>
+ <pre>
+ <code>MessageConsumer deadLetterConsumer = session.createConsumer(expiryQueue);</code>
+ </pre>
+
+ <li>We consume a message from the dead letter queue:</li>
+ <pre>
+ <code>messageReceived = (TextMessage)deadLetterConsumer.receive(5000);</code>
+ </pre>
+
+ <li>The message consumed from the <em>dead letter queue</em> has the <em>same content</em> than the message which was sent to the <em>queue</em>
+ <pre>
+ <code>System.out.println("Received message from " + deadLetterQueue.getQueueName() + ": " + messageReceived.getText());</code>
+ </pre>
+
+ <p>JMS does not specify the notion of dead letter destinations and messages. From JMS point of view, the message received from the dead letter queue
+ is a <strong>different</strong> message than the message removed from the queue after the unsuccessful delivery attempts:
+ the messages have the same content (properties and body) but their JMS headers differ.<br />
+ JBoss Messaging defines additional properties for messages received from a dead letter destination</p>
+
+ <li>The message's destination is the dead letter queue</li>
+ <pre>
+ <code>System.out.println("Destination of the message: " + ((Queue)messageReceived.getJMSDestination()).getQueueName());</code>
+ </pre>
+
+ <li>The <strong>origin destination</strong> is stored in the <code>_JBM_ORIG_DESTINATION</code> property
+ <pre>
+ <code>System.out.println("*Origin destination* of the message: " + messageReceived.getStringProperty("_JBM_ORIG_DESTINATION"));</code>
+ </pre>
+
+ <li>We do not forget to commit the session to acknowledge that we have received the message from the dead letter queue</li>
+ <pre>
+ <code>session.commit();</code>
+ </pre>
+
+ </p>
+ <li>And finally, <b>always</b> remember to close your JMS connections after use, in a <code>finally</code> block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects</li>
+
+ <pre>
+ <code>finally
+ {
+ if (connection != null)
+ {
+ connection.close();
+ }
+ }</code>
+ </pre>
+
+
+
+ </ol>
+ </body>
+</html>
\ No newline at end of file
Added: trunk/examples/jms/dead-letter/src/org/jboss/jms/example/DeadLetterExample.java
===================================================================
--- trunk/examples/jms/dead-letter/src/org/jboss/jms/example/DeadLetterExample.java (rev 0)
+++ trunk/examples/jms/dead-letter/src/org/jboss/jms/example/DeadLetterExample.java 2009-04-02 16:09:55 UTC (rev 6281)
@@ -0,0 +1,160 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2005-2008, Red Hat Middleware LLC, and individual contributors
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.jms.example;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.jms.Connection;
+import javax.jms.ConnectionFactory;
+import javax.jms.MessageConsumer;
+import javax.jms.MessageProducer;
+import javax.jms.Queue;
+import javax.jms.Session;
+import javax.jms.TextMessage;
+import javax.naming.InitialContext;
+
+/**
+ * An example showing how messages are moved to dead letter destination when they are unsuccessfully delivered multiple times
+ *
+ * @author <a href="mailto:jmesnil at redhat.com">Jeff Mesnil</a>
+ *
+ */
+public class DeadLetterExample extends JMSExample
+{
+ public static void main(String[] args)
+ {
+ new DeadLetterExample().run(args);
+ }
+
+ public void runExample() throws Exception
+ {
+ Connection connection = null;
+ try
+ {
+ // Step 1. Create an initial context to perform the JNDI lookup.
+ InitialContext initialContext = getContext();
+
+ // Step 2. Perfom a lookup on the queue
+ Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");
+
+ // Step 3. Perform a lookup on the Connection Factory
+ ConnectionFactory cf = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
+
+ // Step 4.Create a JMS Connection
+ connection = cf.createConnection();
+
+ // Step 5. Create a * transacted* JMS Session
+ Session session = connection.createSession(true, 0);
+
+ // Step 6. Create a JMS Message Producer
+ MessageProducer producer = session.createProducer(queue);
+
+ // Step 7. Create a Text Message
+ TextMessage message = session.createTextMessage("this is a text message");
+
+ // Step 8. Send the Message
+ producer.send(message);
+ System.out.println("Sent message to " + queue.getQueueName() + ": " + message.getText());
+
+ // Step 9. Commit the session to effectively send the message
+ session.commit();
+
+ // Step 10. Create a JMS Message Consumer for the queue
+ MessageConsumer messageConsumer = session.createConsumer(queue);
+
+ // Step 11. Start the Connection
+ connection.start();
+
+ // Step 12. We receive a message...
+ TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("1st delivery from " + queue.getQueueName() + ": " + messageReceived.getText());
+
+ // Step 13. ... but we roll back the session. the message returns to the queue ready to be redelivered
+ session.rollback();
+
+ // Step 14. We receive a message and roll back the session a second time
+ messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("2nd delivery from " + queue.getQueueName() + ": " + messageReceived.getText());
+ session.rollback();
+
+ // Step 15. We receive a message and roll back the session a third time
+ messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("3rd delivery from " + queue.getQueueName() + ": " + messageReceived.getText());
+ session.rollback();
+
+ // The message has been delivered unsuccessfully 3 times -> it is moved to the dead letter queue.
+
+ // Step 16. The 4th time, call will timeout after 5000ms and messageReceived will be null
+ messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.println("4th delivery from " + queue.getQueueName() + ": " + messageReceived);
+
+ // We will now consume the message from the dead letter queue
+
+ // Step 17. Perform a lookup on the dead letter queue
+ Queue deadLetterQueue = (Queue)initialContext.lookup("/queue/deadLetterQueue");
+
+ // Step 18. Create a JMS Message Consumer for the dead letter queue
+ MessageConsumer deadLetterConsumer = session.createConsumer(deadLetterQueue);
+
+ // Step 19. Receive the message from the dead letter queue
+ messageReceived = (TextMessage)deadLetterConsumer.receive(5000);
+
+ // Step 20. The message sent to the queue was moved to the dead letter queue after 3 unsuccessful deliveries
+ System.out.println("Received message from " + deadLetterQueue.getQueueName() + ": " + messageReceived.getText());
+
+ // The message received from the dead letter queue has the same content than the undelivered message but its JMS headers
+ // differ (from JMS point of view, it's not the same message).
+ // JBoss Messaging defines additional properties for messages received from the dead letter queue
+
+ System.out.println();
+ // Step 21. the messageReceived's destination is now the dead letter queue.
+ System.out.println("Destination of the message: " + ((Queue)messageReceived.getJMSDestination()).getQueueName());
+
+ // Step 22. the *origin* destination is stored in the _JBM_ORIG_DESTINATION property
+ System.out.println("*Origin destination* of the message: " + messageReceived.getStringProperty("_JBM_ORIG_DESTINATION"));
+
+ // Step 23. This time, we commit the session, the delivery from the dead letter queue is successful!
+ session.commit();
+
+ initialContext.close();
+ }
+ finally
+ {
+ // Step 24. Be sure to close our JMS resources!
+ if (connection != null)
+ {
+ connection.close();
+ }
+ }
+ }
+
+ @Override
+ public Set<String> getQueues()
+ {
+ HashSet<String> queues = new HashSet<String>();
+ queues.add("exampleQueue");
+ queues.add("deadLetterQueue");
+ return queues;
+ }
+
+}
Modified: trunk/src/main/org/jboss/messaging/core/deployers/impl/AddressSettingsDeployer.java
===================================================================
--- trunk/src/main/org/jboss/messaging/core/deployers/impl/AddressSettingsDeployer.java 2009-04-02 15:17:42 UTC (rev 6280)
+++ trunk/src/main/org/jboss/messaging/core/deployers/impl/AddressSettingsDeployer.java 2009-04-02 16:09:55 UTC (rev 6281)
@@ -41,6 +41,8 @@
private static final String REDELIVERY_DELAY_NODE_NAME = "redelivery-delay";
+ private static final String MAX_DELIVERY_ATTEMPTS = "max-delivery-attempts";
+
private static final String MAX_SIZE_BYTES_NODE_NAME = "max-size-bytes";
private static final String DROP_MESSAGES_WHEN_FULL_NODE_NAME = "drop-messages-when-full";
@@ -139,6 +141,10 @@
{
addressSettings.setSoloQueue(Boolean.valueOf(child.getTextContent().trim()));
}
+ else if (MAX_DELIVERY_ATTEMPTS.equalsIgnoreCase(child.getNodeName()))
+ {
+ addressSettings.setMaxDeliveryAttempts(Integer.valueOf(child.getTextContent().trim()));
+ }
}
addressSettingsRepository.addMatch(match, addressSettings);
Modified: trunk/src/schemas/jbm-queues.xsd
===================================================================
--- trunk/src/schemas/jbm-queues.xsd 2009-04-02 15:17:42 UTC (rev 6280)
+++ trunk/src/schemas/jbm-queues.xsd 2009-04-02 16:09:55 UTC (rev 6281)
@@ -55,6 +55,9 @@
<xsd:element name="redelivery-delay" type="xsd:unsignedLong"
maxOccurs="1" minOccurs="0">
</xsd:element>
+ <xsd:element name="max-delivery-attempts" type="xsd:unsignedInt"
+ maxOccurs="1" minOccurs="0">
+ </xsd:element>
<xsd:element name="max-size-bytes" type="xsd:long"
maxOccurs="1" minOccurs="0">
</xsd:element>
More information about the jboss-cvs-commits
mailing list