JBoss.orgCommunity Documentation

Chapter 8. Using Core

8.1. Core Messaging Concepts
8.1.1. Message
8.1.2. Address
8.1.3. Queue
8.1.4. ServerLocator
8.1.5. ClientSessionFactory
8.1.6. ClientSession
8.1.7. ClientConsumer
8.1.8. ClientProducer
8.2. A simple example of using Core

HornetQ core is a completely JMS-agnostic messaging system with its own non-JMS API. We call this the core API.

If you don't want to use JMS you can use the core API directly. The core API provides all the functionality of JMS but without much of the complexity. It also provides features that are not available using JMS.

Some of the core messaging concepts are similar to JMS concepts, but core messaging concepts differ in some ways. In general the core messaging API is simpler than the JMS API, since we remove distinctions between queues, topics and subscriptions. We'll discuss each of the major core messaging concepts in turn, but to see the API in detail, please consult the Javadoc.

A client uses a ClientSession for consuming and producing messages and for grouping them in transactions. ClientSession instances can support both transactional and non transactional semantics and also provide an XAResource interface so messaging operations can be performed as part of a JTA transaction.

ClientSession instances group ClientConsumers and ClientProducers.

ClientSession instances can be registered with an optional SendAcknowledgementHandler. This allows your client code to be notified asynchronously when sent messages have successfully reached the server. This unique HornetQ feature, allows you to have full guarantees that sent messages have reached the server without having to block on each message sent until a response is received. Blocking on each messages sent is costly since it requires a network round trip for each message sent. By not blocking and receiving send acknowledgements asynchronously you can create true end to end asynchronous systems which is not possible using the standard JMS API. For more information on this advanced feature please see the section Chapter 20, Guarantees of sends and commits.

Here's a very simple program using the core messaging API to send and receive a message:

ServerLocator locator = HornetQClient.createServerLocatorWithoutHA(new TransportConfiguration(
                                           InVMConnectorFactory.class.getName()));

ClientSessionFactory factory =  locator.createClientSessionFactory();

ClientSession session = factory.createSession();

session.createQueue("example", "example", true);

ClientProducer producer = session.createProducer("example");

ClientMessage message = session.createMessage(true);

message.getBodyBuffer().writeString("Hello");

producer.send(message);

session.start();

ClientConsumer consumer = session.createConsumer("example");

ClientMessage msgReceived = consumer.receive();

System.out.println("message = " + msgReceived.getBodyBuffer().readString());

session.close();