There are times when some messages are delivered unsuccessfully like if the transacted session used to consume them has rolled back for some reason. Such a message goes back to the JMS destination and gets ready to be redelivered as per the configuration settings. It can be possible for a message to be delivered again and again without any success and those messages are never delivered and remain in the destination. These types of messages can become POISON messages, due to which other messages in the queue cannot get consumed and a plie of messages stacks over the queue and result many other issues.

So the question comes into the picture how to prevent this? Here comes the Dead Letter Queue (DLQ) to the rescue, after a specified unsuccessful delivery attempts (i.e. MaxDeliveryAttempts), the message is removed from the destination and moves it inside the defined Dead Letter Queue (DLQ) where the messages can be consumed for further investigation.

Poison Message


Dead Letter Queue (DLQ)


Features To Discuss

  1. We would be using the default DLQ which comes with JBoss
  2. In this example would make sure that if a message is having a string as “Hello World”, then that message would be rolled backed after specified unsuccessful delivery attempts and would be moved in the DLQ and other messages can be consumed without any issue.

Working example of Dead Letter Queue in JBoss

  1. Create a queue from the Admin-console or even create “*-service.xml” file and place it in the “/profile/deploy” directory. Where * means your Queue name as shown in the below example

    TestQueue-service.xml

  2. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <server>
        <mbean xmbean-dd="xmdesc/Queue-xmbean.xml" name="jboss.messaging.destination:service=Queue,name=TestQueue" code="org.jboss.jms.server.destination.QueueService">
    	<!-- Defining the DLQ for this TestQueue -->
            <attribute name="DLQ"> jboss.messaging.destination:name=DLQ,service=Queue</attribute>
            <attribute name="JNDIName">TestQueue</attribute>
    	<!-- The number of times, undilivered messages would be resend -->
    	<attribute name="MaxDeliveryAttempts">3</attribute>
            <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
            <depends>jboss.messaging:service=PostOffice</depends>
        </mbean>
    </server>
    
  3. That’s it !!! You are done configuring a simple queue having a MaxDeliveryAttempts as 3 with DLQ, now if a message does not get delivered in 3 attempts then that message would be moved to DLQ. Let’s test this out using the sender and receiver Java code.

Testing

  1. Create a Directory somewhere in your file system like: “/urs/JBoss/JBM/Queue” to write the QueueSend.java and QueueReceive.java programs.
  2. In QueueSend.java copy the below program
    import java.io.*;
    import java.io.*;
    import java.util.Hashtable;
    import javax.jms.JMSException;
    import javax.jms.Queue;
    import javax.jms.QueueConnection;
    import javax.jms.QueueConnectionFactory;
    import javax.jms.QueueSender;
    import javax.jms.QueueSession;
    import javax.jms.Session;
    import javax.jms.TextMessage;
    import javax.naming.Context;
    import javax.naming.InitialContext;
    import javax.naming.NamingException;
    
    public class QueueSend
    {
    public final static String JNDI_FACTORY="org.jnp.interfaces.NamingContextFactory";
    
    //*************** Connection Factory JNDI name *************************
    public final static String JMS_FACTORY="/ConnectionFactory";
    
    //*************** Connection Factory JNDI name *************************
    public final static String QUEUE="/TestQueue";
    
    
    private QueueConnectionFactory qconFactory;
    private QueueConnection qcon;
    private QueueSession qsession;
    private QueueSender qsender;
    private Queue queue;
    private TextMessage msg;
    
    public void init(Context ctx, String queueName)throws NamingException, JMSException
    {
    qconFactory = (QueueConnectionFactory) ctx.lookup(JMS_FACTORY);
    qcon = qconFactory.createQueueConnection();
    qsession = qcon.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
    queue = (Queue) ctx.lookup(queueName);
    qsender = qsession.createSender(queue);
    msg = qsession.createTextMessage();
    qcon.start();
    }
    
    public void send(String message) throws JMSException {
    msg.setText(message);
    qsender.send(msg);
    }
    
    public void close() throws JMSException {
    qsender.close();
    qsession.close();
    qcon.close();
    }
    
    public static void main(String[] args) throws Exception {
    if (args.length != 1) {
    System.out.println("Usage: java QueueSend URL");
    return;
    }
    InitialContext ic = getInitialContext(args[0]);
    QueueSend qs = new QueueSend();
    qs.init(ic, QUEUE);
    readAndSend(qs);
    qs.close();
    }
    
    private static void readAndSend(QueueSend qs) throws IOException, JMSException
    {
    String line="Test Message Body with counter = ";
    BufferedReader br=new BufferedReader(new InputStreamReader(System.in));
    boolean readFlag=true;
    System.out.println("ntStart Sending Messages (Enter QUIT to Stop):n");
    while(readFlag)
    {
    System.out.print("<Msg_Sender> ");
    String msg=br.readLine();
    if(msg.equals("QUIT") || msg.equals("quit"))
    {
    qs.send(msg);
    System.exit(0);
    }
    qs.send(msg);
    System.out.println();
    }
    br.close();
    }
    
    private static InitialContext getInitialContext(String url) throws NamingException
    {
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, JNDI_FACTORY);
    env.put(Context.PROVIDER_URL, url);
    return new InitialContext(env);
    }
    }
    
  3. In QueueReceive.java copy the below program, which has a creating a transacted JMS Session and in “onMessage” we are checking it the text message which is been received contents “hello world” ignoring the case would get roll-backed if not would get committed to test our DLQ.
    import java.util.Hashtable;
    import javax.jms.*;
    import javax.naming.Context;
    import javax.naming.InitialContext;
    import javax.naming.NamingException;
    
    public class QueueReceive implements MessageListener
    {
    public final static String JNDI_FACTORY="org.jnp.interfaces.NamingContextFactory";
    
    //*************** Connection Factory JNDI name *************************
    public final static String JMS_FACTORY="/ConnectionFactory";
    
    //*************** Connection Factory JNDI name *************************
    public final static String QUEUE="/TestQueue";
    
    
    private QueueConnectionFactory qconFactory;
    private QueueConnection qcon;
    private QueueSession qsession;
    private QueueReceiver qreceiver;
    private Queue queue;
    private boolean quit = false;
    
    public void onMessage(Message msg)
    {
    	try 
    	{
    		String msgText;
    		if (msg instanceof TextMessage)
    		{
    			msgText = ((TextMessage)msg).getText();
    		}
    		else
    		{
    			msgText = msg.toString();
    		}
    		if (msgText.equalsIgnoreCase("hello world"))
    		{
    			System.out.println("nt<Msg_Receiver> "+ msgText +", hence rolling back");
    			// Here we are rolling back the session. 
    			// The "Hello World" message which we received is not committed, hence it's undelivered and goes back to the TestQ
    			qsession.rollback();
    		}
    		else
    		{
    			System.out.println("nt<Msg_Receiver> "+ msgText );
    			// Here we are committing the session to acknowledge that we have received the message from the TestQ
    			qsession.commit();
    		}
    			
    		if (msgText.equalsIgnoreCase("quit"))
    		{
    			synchronized(this)
    			{
    				quit = true;
    				this.notifyAll();
    			}
    		}
    	}
    	catch (JMSException jmse)
    	{
    	jmse.printStackTrace();
    	}
    }
    
    
    public void init(Context ctx, String queueName) throws NamingException, JMSException
    {
    	qconFactory = (QueueConnectionFactory) ctx.lookup(JMS_FACTORY);
    	qcon = qconFactory.createQueueConnection();
    
    	//Creating a *transacted* JMS Session to test our DLQ
    	qsession = qcon.createQueueSession(true, 0);	
    
    	queue = (Queue) ctx.lookup(queueName);
    	qreceiver = qsession.createReceiver(queue);
    	qreceiver.setMessageListener(this);
    	qcon.start();	
    }
    
    public void close()throws JMSException
    {
    qreceiver.close();
    qsession.close();
    qcon.close();
    }
    
    public static void main(String[] args) throws Exception
    {
    if (args.length != 1)
    {
    System.out.println("Usage: java QueueReceive URL");
    return;
    }
    InitialContext ic = getInitialContext(args[0]);
    QueueReceive qr = new QueueReceive();
    qr.init(ic, QUEUE);
    System.out.println("JMS Ready To Receive Messages (To quit, send a "quit" message from QueueSender.class).");
    
    synchronized(qr)
    {
    while (! qr.quit)
    {
    try
    {
    qr.wait();
    }
    catch (InterruptedException ie)
    {}
    }
    }
    qr.close();
    }
    
    private static InitialContext getInitialContext(String url) throws NamingException
    {
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, JNDI_FACTORY);
    env.put(Context.PROVIDER_URL, url);
    return new InitialContext(env);
    }
    }
    
  4. Now open 2– command prompt and run the “. ./setJBossEnv.sh” by adding two DOTs separated by a single space, in both the prompts to set the Environment (PATH & CLASSPATH).
  5. setJBossEnv.sh

    #!/bin/sh
    echo "Exporting JBOSS_HOME...."
    export JBOSS_HOME=/Jboss/AS5.1/jboss-as   <---- Change as per your environment
    echo "JBOSS_HOME Exported....!!!"
    echo ""
    echo "Exporting JAVA_HOME...."
    export JAVA_HOME=/Jdk/jdk1.6.0_21    <---- Change as per your environment
    echo "JBOSS_HOME Exported....!!!"
    echo ""
    echo "Exporting CLASSPATH...."
    export CLASSPATH=$JBOSS_HOME/client/jbossall-client.jar:$JBOSS_HOME/client/jboss-javaee.jar:$JBOSS_HOME/common/lib/jnpserver.jar:$JBOSS_HOME/client/jboss-logging-spi.jar:$JBOSS_HOME/lib/jboss-javaee.jar:$JBOSS_HOME/common/lib/servlet-api.jar:$JBOSS_HOME/common/lib/log4j.jar:$CLASSPATH:.:
    echo "CLASSPATH Exported....!!!"
    echo ""
    echo "Exporting PATH...."
    export PATH=$JAVA_HOME/bin:$PATH
    echo "PATH Exported....!!!"
    echo ""
    echo "========================================================================"
    echo "JBOSS_HOME = " $JBOSS_HOME
    echo ""
    echo "JAVA_HOME = " $JAVA_HOME
    echo ""
    echo "CLASSPATH = " $CLASSPATH
    echo ""
    echo "PATH = " $PATH
    echo "========================================================================"
    
  6. Then compile the QueueSend.java and QueueReceive.java programs.
  7. Now run the code with the following command
  8. Prompt-1

    java QueueSend jnp://localhost:1099
     

    Prompt-2

    java QueueReceive jnp://localhost:1099
     

    Note:
    With the “java QueueSend” and “java QueueReceive” command you have to give the<Protocol>://<IP-address>:<Port number>of the managed servers in different prompts.

  9. Once this is been done try to send some messages (i.e. with “hello world” one of them ) in the Prompt-1 which can be revived on Prompt-2. , however the message which is “hellow world” would be rollbacked and as per the “MaxDeliveryAttempts” value 3 times it would be re-sent and then it would be moved to the DLQ, which can be seen in the console under
    Admin console path:
    Resources – JBoss Messaging – DLQ – “Message Count”

If you enjoyed this post, please consider leaving a comment or subscribing to the RSS feed to have future articles delivered to your feed reader.