JBoss HornetQ simple tutorial

HornetQ is an open source project to build a multi-protocol, embeddable, very high performance, clustered, asynchronous messaging system.
Why learning another messaging system ? here are a few good reasons: 

1. Hornet Q is an open source messaging system which can be used as standalone or on any application server or even embedded in your applications.
2. HornetQ delivers amazing messaging performance.
3. HornetQ provides seamless clustering capabilities.
4. Most important for us: it's the default Messaging system in JBoss AS 6.

It takes just a few minutes to be operative, let's start:

Download HornetQ from JBoss.org

http://www.jboss.org/hornetq/downloads.html

Download the latest stable release and unzip in a convenient location.

Start HornetQ

HornetQ can be started in 3 ways: 

• Standalone server
• Inside an application server
• Embedded in your applications

#1 Standalone server

Launching HornetQ as standalone server is fairly trivial: reach the "bin" folder in your HornetQ distribution and launchrun.bat/run.sh

#2 Inside JBoss AS 4.x-5.x-6.x

If you don't want to run HornetQ as standalone but embedded in jBoss AS there's a simple script in the folder HORNETQ-HOME\config\jboss-as named build.bat/build.sh.
The only requirement is to set the JBOSS_HOME environment variable.


This will create two additional JBoss configurations default-with-hornetq and all-with-hornetq. The former can be used to run JBoss as standalone server and the latter as clustered node.

Now launch JBoss AS using the -c parameter. For example:
run -c default-with-hornetq

#3 Embedded in your Java code

HornetQ can be started as well in embedded mode. This can be particularly useful for testing purposes if you don't want to start/stop manually the server on your machine.

An example of how to start an embedded HornetQ server is provided in HornetQExample.java file which can be found in the HORNETQ_HOME/examples/common/src/org/hornetq/common/example

Inspect HornetQ configuration

The configuration of HornetQ is split in several files. The following table resumes the basics of its configuration.

File	Content
hornetq-jboss-beans.xml	Micro container configuration file.
hornetq-configuration.xml	Main configuration file. Used to change JMS Storage directories and Message settings.
hornetq-jms.xml	JMS Queue/Topic configuration.
jms-ds.xml	JMS Provider configuration and Connection factory configuration.
login-config.xml	The XML based JAAS login configuration.

As a developer you are likely to be interested to uodate the hornetq-jms.xml file to add/remove new Queue/Topics.

Deploy a simple MDB 

Deploying an MDB is fairly trivial. The only difference with a MDB powered by another JMS provider is the@ResourceAdapter annotation which informs the EJB container to use HornetQ resource adapter configuration.

package com.sample;

import org.jboss.ejb3.annotation.ResourceAdapter;

import javax.ejb.*;
import javax.jms.*;

@MessageDriven(name = "MDBExample",
               activationConfig =
                     {
                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
                     })
 
@ResourceAdapter("hornetq-ra.rar")
public class MDBExample implements MessageListener
{
   public void onMessage(Message message)
   {
      try
      {
         TextMessage textMessage = (TextMessage)message;
 
         String text = textMessage.getText();
         
         System.out.println("message " + text);

      }
      catch (Exception e)
      {
         e.printStackTrace();
      }
   }
}

Ok. In order to test this MDB you have to update your hornetq-jms.xml file (which is located, if you are running HornetQ inside JBoss in deploy\hornetq.sar) by adding the testQueue definition:

 

<queue name="testQueue">
      <entry name="/queue/testQueue"/>
</queue>

And finally here's a generic test client which can be used to send messages to the "testQueue":

package com.sample;

 

import java.util.Properties;

import javax.jms.*;

import javax.naming.Context;

 

public class QueueExample  

{

 

    public void example() throws Exception

    {

        String destinationName = "queue/testQueue";

 

        Context ic = null;

        ConnectionFactory cf = null;

        Connection connection =  null;

 

        try

        {        

            ic = getInitialContext();

 

            cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");

            Queue queue = (Queue)ic.lookup(destinationName);

 

            connection = cf.createConnection();

            Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);

            MessageProducer publisher = session.createProducer(queue);

            MessageConsumer subscriber = session.createConsumer(queue);

 

            connection.start();

 

            TextMessage message = session.createTextMessage("Hello!");

            publisher.send(message);

            System.out.println("Message sent!");

  

 

        }

        finally

        {        

            if(ic != null)

            {

                try

                {

                    ic.close();

                }

                catch(Exception e)

                {

                    throw e;

                }

            }

 

            closeConnection(connection);

        }

    }

    private void closeConnection(Connection con)

    {     

        try

        {

            if (con != null)

            {

                con.close();

            }        

        }

        catch(JMSException jmse)

        {

            System.out.println("Could not close connection " + con +" exception was " + jmse);

        }

    }

 

 

    public static void main(String[] args) throws Exception

    {

        new QueueExample().example();

    }

    public static Context getInitialContext( )

    throws javax.naming.NamingException {

 

        Properties p = new Properties( );

        p.put(Context.INITIAL_CONTEXT_FACTORY,

                "org.jnp.interfaces.NamingContextFactory");

        p.put(Context.URL_PKG_PREFIXES,

        " org.jboss.naming:org.jnp.interfaces");

        p.put(Context.PROVIDER_URL, "jnp://localhost:1099");

        return new javax.naming.InitialContext(p);

    } 

}

Your example is completed. Remeber to add HornetQ libraries into your build path as shown here:

References:
http://www.jboss.org/hornetq/docs.html