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. It's the default Messaging system in JBoss EAP 6 and WildFly 8/9.

Since WildFly 10 and JBoss EAP 7 Apache Artemis MQ is the default Messagins system. This project, however, is derived from the HornetQ project, recently donated to the  Apache foundation. The new messaging provides retains compatibility with the former HornetQ while providing several new features.

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

Download HornetQ from JBoss.org

Download the latest stable release from http://www.jboss.org/hornetq/downloads.html 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 HornetQ server

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

start hornet

#2 Inside JBoss EAP 6 / WildFly 8

HornetQ is the JBoss EAP 6 and WildFly 8 messasing broker. To be more specific, the messaging suite of the application server is based on two core building blocks which let you create and consume JMS messages:
  • HornetQ itself is the JBoss EAP’s messaging provider featuring a multi-protocol, embeddable, very high performance, clusterable messaging implementation.
  • Netty project (http://netty.io/index.html) is an asynchronous event-driven network application framework which is used by HornetQ to transport messages from one JVM to another.
Please note that the messaging subsystem is not included in the default server configuration, therefore in order to use it you have to point to one of the standalone-full.xml or standalone-full-ha.xml configurations.So, for example, if you plan to run JMS applications on a non- clustered EAP server all you have to do is starting it like that:
$ ./standalone.sh –c standalone-full.xml

#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 contained in the examples/core/embedded which can be found in the HornetQ distribution:
package org.hornetq.core.example;

import java.util.Date;

import org.hornetq.api.core.TransportConfiguration;
import org.hornetq.api.core.client.ClientConsumer;
import org.hornetq.api.core.client.ClientMessage;
import org.hornetq.api.core.client.ClientProducer;
import org.hornetq.api.core.client.ClientSession;
import org.hornetq.api.core.client.ClientSessionFactory;
import org.hornetq.api.core.client.HornetQClient;
import org.hornetq.api.core.client.ServerLocator;
import org.hornetq.core.config.Configuration;
import org.hornetq.core.config.impl.ConfigurationImpl;
import org.hornetq.core.remoting.impl.invm.InVMAcceptorFactory;
import org.hornetq.core.remoting.impl.invm.InVMConnectorFactory;
import org.hornetq.core.server.HornetQServer;
import org.hornetq.core.server.HornetQServers;

 * This example shows how to run a HornetQ core client and server embedded in your
 * own application
 * @author Tim Fox
public class EmbeddedExample

   public static void main(final String[] args) throws Exception
         // Step 1. Create the Configuration, and set the properties accordingly
         Configuration configuration = new ConfigurationImpl();
         //we only need this for the server lock file
         configuration.getAcceptorConfigurations().add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));

         // Step 2. Create and start the server
         HornetQServer server = HornetQServers.newHornetQServer(configuration);

         // Step 3. As we are not using a JNDI environment we instantiate the objects directly
         ServerLocator serverLocator = HornetQClient.createServerLocatorWithoutHA(new TransportConfiguration(InVMConnectorFactory.class.getName()));
         ClientSessionFactory sf = serverLocator.createSessionFactory();

         // Step 4. Create a core queue
         ClientSession coreSession = sf.createSession(false, false, false);

         final String queueName = "queue.exampleQueue";

         coreSession.createQueue(queueName, queueName, true);


         ClientSession session = null;


            // Step 5. Create the session, and producer
            session = sf.createSession();

            ClientProducer producer = session.createProducer(queueName);

            // Step 6. Create and send a message
            ClientMessage message = session.createMessage(false);

            final String propName = "myprop";

            message.putStringProperty(propName, "Hello sent at " + new Date());

            System.out.println("Sending the message.");


            // Step 7. Create the message consumer and start the connection
            ClientConsumer messageConsumer = session.createConsumer(queueName);

            // Step 8. Receive the message.
            ClientMessage messageReceived = messageConsumer.receive(1000);
            System.out.println("Received TextMessage:" + messageReceived.getStringProperty(propName));
            // Step 9. Be sure to close our resources!
            if (sf != null)

            // Step 10. Stop the server
      catch (Exception e)
         throw e;

Inspect HornetQ configuration

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

File Content
hornetq-beans.xml The core MBean server and Port settings.
hornetq-configuration.xml Main configuration file. Used to change JMS Storage directories and Message settings.
hornetq-jms.xml JMS Queue/Topic configuration.
hornetq-users.xml Users configuration
logging.properties The JUL configuration of the Server
As a developer you are likely to be interested to uodate the hornetq-jms.xml file to add/remove new Queue/Topics.

Related articles available on mastertheboss.com

How to configure a Queue in JBoss ?

This article has been moved here: JBoss JMS configuration

How to create a Queue with Jmx Console ?

  Bring up the JMX Console in your browser and look for the sect

JBoss JMS Queue example

The following article shows how to create a simple JMS Queue Prod

JBoss JMS Topic example

The following article shows how to create a simple JMS Topic Publ

How do I configure a Queue/Topic to work in a cluster?

  JBoss AS 5 Just set the Clustered attribute to "true" in your

JBoss JMS configuration

The Java Messaging Service (JMS) has been implemented by means of

Follow us on Twitter