Chapter 11. Examples

The HornetQ distribution comes with over 65 run out-of-the-box examples demonstrating many of the features.

The examples are available in the distribution, in the examples directory. Examples are split into JMS and core examples. JMS examples show how a particular feature can be used by a normal JMS client. Core examples show how the equivalent feature can be used by a core messaging client.

A set of Java EE examples are also provided which need the JBoss Application Server installed to be able to run.

11.1. JMS Examples

To run a JMS example, simply cd into the appropriate example directory and type ant.

You will need to have Apache 1.7.0 or later ant installed on your system with the ant bin directory on your path.

Here's a listing of the examples with a brief description.

11.1.1. Application-Layer Failover

HornetQ implements fully transparent automatic failover of connections from a live to backup node, this requires no special coding for failover, and is described in a different example. Automatic failover requires server replication.

However, HornetQ also supports Application-Layer failover, useful in the case that replication is not enabled on the server side.

With Application-Layer failover, it's up to the application to register a JMS ExceptionListener with HornetQ which will be called by HornetQ in the event that connection failure is detected.

The code in the ExceptionListener then recreates the JMS connection, session, etc on another node and the application can continue.

Application-layer failover is an alternative approach to High Availability (HA). Application-layer failover differs from automatic failover in that some client side coding is required in order to implement this. Also, with Application-layer failover, since the old session object dies and a new one is created, any uncommitted work in the old session will be lost, and any unacknowledged messages might be redelivered.

11.1.2. Automatic (Transparent) Failover

The automatic-failover example demonstrates two servers coupled as a live-backup pair for high availability (HA), and a client connection transparently failing over from live to backup when the live server is crashed.

HornetQ implements seamless, transparent failover of client connections between live and backup servers. This is implemented by the replication of state between live and backup nodes. When replication is configured and a live node crashes, the client connections can carry on as if nothing happened and carry on sending and consuming messages.

11.1.3. Automatic Reconnect

The reconnect-same-node example demonstrates how HornetQ connections can be configured to be resilient to temporary network failures.

In the case of a network failure being detected, either as a result of a failure to read/write to the connection, or the failure of a pong to arrive back from the server in good time after a ping is sent, instead of failing the connection immediately and notifying any user ExceptionListener objects, HornetQ can be configured to automatically retry the connection, and reconnect to the server when it becomes available again across the network.

11.1.4. Browser

The browser example shows you how to use a JMS QueueBrowser with HornetQ.

Queues are a standard part of JMS, please consult the JMS 1.1 specification for full details.

A QueueBrowser is used to look at messages on the queue without removing them. It can scan the entire content of a queue or only messages matching a message selector.

11.1.5. Core Bridge Example

The bridge example demonstrates a core bridge deployed on one server, which consumes messages from a local queue and forwards them to an address on a second server.

Core bridges are used to create message flows between any two HornetQ servers which are remotely separated. Core bridges are resilient and will cope with temporary connection failure allowing them to be an ideal choice for forwarding over unreliable connections, e.g. a WAN.

11.1.6. Client Kickoff

The client-kickoff example shows how to terminate client connections given an IP address using the JMX management API.

11.1.7. Client Side Load-Balancing

The client-side-load-balancing example demonstrates how subsequent connections created from a JMS ConnectionFactory can be created to different nodes of the cluster. In other words it demonstrates how HornetQ does client side load balancing of connections across the cluster.

11.1.8. Clustered Queue

The clustered-queue example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster. We then create a consumer for the queue on each node, and we create a producer on only one of the nodes. We then send some messages via the producer, and we verify that both consumers receive the sent messages in a round-robin fashion.

11.1.9. Clustered Standalone

The clustered-standalone example demonstrates how to configure and starts 3 cluster nodes on the same machine to form a cluster. A subscriber for a JMS topic is created on each node, and we create a producer on only one of the nodes. We then send some messages via the producer, and we verify that the 3 subscribers receive all the sent messages.

11.1.10. Clustered Topic

The clustered-topic example demonstrates a JMS topic deployed on two different nodes. The two nodes are configured to form a cluster. We then create a subscriber on the topic on each node, and we create a producer on only one of the nodes. We then send some messages via the producer, and we verify that both subscribers receive all the sent messages.

11.1.11. Dead Letter

The dead-letter example shows you how to define and deal with dead letter messages. 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 be 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.

To prevent this, messaging systems define dead letter messages: after a specified unsuccessful delivery attempts, the message is removed from the destination and put instead in a dead letter destination where they can be consumed for further investigation.

11.1.12. Delayed Redelivery

The delayed-redelivery example demonstrates how HornetQ can be configured to provide a delayed redelivery in the case a message needs to be redelivered.

Delaying redelivery can often be useful in the case that clients regularly fail or roll-back. Without a delayed redelivery, the system can get into a "thrashing" state, with delivery being attempted, the client rolling back, and delivery being re-attempted in quick succession, using up valuable CPU and network resources.

11.1.13. Divert

HornetQ diverts allow messages to be transparently "diverted" or copied from one address to another with just some simple configuration defined on the server side.

11.1.14. Durable Subscription

The durable-subscription example shows you how to use a durable subscription with HornetQ. Durable subscriptions are a standard part of JMS, please consult the JMS 1.1 specification for full details.

Unlike non-durable subscriptions, the key function of durable subscriptions is that the messages contained in them persist longer than the lifetime of the subscriber - i.e. they will accumulate messages sent to the topic even if there is no active subscriber on them. They will also survive server restarts or crashes. Note that for the messages to be persisted, the messages sent to them must be marked as persistent messages.

11.1.15. Embedded

The embedded example shows how to embed the HornetQ server within your own code.

11.1.16. HTTP Transport

The http-transport example shows you how to configure HornetQ to use the HTTP protocol as its transport layer.

11.1.17. Instantiate JMS Objects Directly

Usually, JMS Objects such as ConnectionFactory, Queue and Topic instances are looked up from JNDI before being used by the client code. This objects are called "administered objects" in JMS terminology.

However, in some cases a JNDI server may not be available or desired. To come to the rescue HornetQ also supports the direct instantiation of these administered objects on the client side so you don't have to use JNDI for JMS.

11.1.18. Interceptor

HornetQ allows an application to use an interceptor to hook into the messaging system. Interceptors allow you to handle various message events in HornetQ.

11.1.19. JAAS

The jaas example shows you how to configure HornetQ to use JAAS for security. HornetQ can leverage JAAS to delegate user authentication and authorization to existing security infrastructure.

11.1.20. JMX Management

The jmx example shows how to manage HornetQ using JMX.

11.1.21. Large Message

The large-message example shows you how to send and receive very large messages with HornetQ. HornetQ supports the sending and receiving of huge messages, much larger than can fit in available RAM on the client or server. Effectively the only limit to message size is the amount of disk space you have on the server.

Large messages are persisted on the server so they can survive a server restart. In other words HornetQ doesn't just do a simple socket stream from the sender to the consumer.

11.1.22. Last-Value Queue

The last-value-queue example shows you how to define and deal with last-value queues. Last-value queues are special queues which discard any messages when a newer message with the same value for a well-defined last-value property is put in the queue. In other words, a last-value queue only retains the last value.

A typical example for last-value queue is for stock prices, where you are only interested by the latest price for a particular stock.

11.1.23. Load Balanced Clustered Queue

The clustered-queue example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster.

We then create a consumer on the queue on each node, and we create a producer on only one of the nodes. We then send some messages via the producer, and we verify that both consumers receive the sent messages in a round-robin fashion.

In other words, HornetQ load balances the sent messages across all consumers on the cluster

11.1.24. Management

The management example shows how to manage HornetQ using JMS Messages to invoke management operations on the server.

11.1.25. Management Notification

The management-notification example shows how to receive management notifications from HornetQ using JMS messages. HornetQ servers emit management notifications when events of interest occur (consumers are created or closed, destinations are created or deleted, security authentication fails, etc.).

11.1.26. Message Consumer Rate Limiting

With HornetQ you can specify a maximum consume rate at which a JMS MessageConsumer will consume messages. This can be specified when creating or deploying the connection factory.

If this value is specified then HornetQ will ensure that messages are never consumed at a rate higher than the specified rate. This is a form of consumer throttling.

11.1.27. Message Counter

The message-counters example shows you how to use message counters to obtain message information for a JMS queue.

11.1.28. Message Expiration

The expiry example shows you how to define and deal with message expiration. Messages can be retained in the messaging system for a limited period of time before being removed. JMS specification states that clients should not receive messages that have been expired (but it does not guarantee this will not happen).

HornetQ can assign an expiry destination to a given queue so that when messages are expired, they are removed from the queue and sent to the expiry destination. These "expired" messages can later be consumed from the expiry destination for further inspection.

11.1.29. Message Group

The message-group example shows you how to configure and use message groups with HornetQ. Message groups allow you to pin messages so they are only consumed by a single consumer. Message groups are sets of messages that has the following characteristics:

  • Messages in a message group share the same group id, i.e. they have same JMSXGroupID string property values

  • The consumer that receives the first message of a group will receive all the messages that belongs to the group

11.1.30. Message Producer Rate Limiting

The producer-rte-limit example demonstrates how, with HornetQ, you can specify a maximum send rate at which a JMS message producer will send messages.

11.1.31. Message Priority

Message Priority can be used to influence the delivery order for messages.

It can be retrieved by the message's standard header field 'JMSPriority' as defined in JMS specification version 1.1.

The value is of type integer, ranging from 0 (the lowest) to 9 (the highest). When messages are being delivered, their priorities will effect their order of delivery. Messages of higher priorities will likely be delivered before those of lower priorities.

Messages of equal priorities are delivered in the natural order of their arrival at their destinations. Please consult the JMS 1.1 specification for full details.

11.1.32. Message Redistribution

The queue-message-redistribution example demonstrates message redistribution between queues with the same name deployed in different nodes of a cluster.

11.1.33. No Consumer Buffering

By default, HornetQ consumers buffer messages from the server in a client side buffer before you actually receive them on the client side. This improves performance since otherwise every time you called receive() or had processed the last message in a MessageListener onMessage() method, the HornetQ client would have to go the server to request the next message, which would then get sent to the client side, if one was available.

This would involve a network round trip for every message and reduce performance. Therefore, by default, HornetQ pre-fetches messages into a buffer on each consumer.

In some case buffering is not desirable, and HornetQ allows it to be switched off. This example demonstrates that.

11.1.34. Paging

The paging example shows how HornetQ can support huge queues even when the server is running in limited RAM. It does this by transparently paging messages to disk, and depaging them when they are required.

11.1.35. Pre-Acknowledge

Standard JMS supports three acknowledgement modes: AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, and DUPS_OK_ACKNOWLEDGE. For a full description on these modes please consult the JMS specification, or any JMS tutorial.

All of these standard modes involve sending acknowledgements from the client to the server. However in some cases, you really don't mind losing messages in event of failure, so it would make sense to acknowledge the message on the server before delivering it to the client. This example demonstrates how HornetQ allows this with an extra acknowledgement mode.

11.1.36. Queue

A simple example demonstrating a JMS queue.

11.1.37. Queue Requestor

A simple example demonstrating a JMS queue requestor.

11.1.38. Queue with Message Selector

The queue-selector example shows you how to selectively consume messages using message selectors with queue consumers.

11.1.39. Request-Response

A simple example showing the JMS request-response pattern.

11.1.40. Scheduled Message

The scheduled-message example shows you how to send a scheduled message to a JMS Queue with HornetQ. Scheduled messages won't get delivered until a specified time in the future.

11.1.41. Security

The security example shows you how configure and use role based queue security with HornetQ.

11.1.42. Send Acknowledgements

The send-acknowledgements example shows you how to use HornetQ's advanced asynchronous send acknowledgements feature to obtain acknowledgement from the server that sends have been received and processed in a separate stream to the sent messages.

11.1.43. Static Message Selector

The static-selector example shows you how to configure a HornetQ core queue with static message selectors (filters).

11.1.44. Static Message Selector Using JMS

The static-selector-jms example shows you how to configure a HornetQ queue with static message selectors (filters) using JMS.

11.1.45. SSL Transport

The ssl-enabled shows you how to configure SSL with HornetQ to send and receive message.

11.1.46. Symmetric Cluster

The symmetric-cluster example demonstrates a symmetric cluster set-up with HornetQ.

HornetQ has extremely flexible clustering which allows you to set-up servers in many different topologies. The most common topology that you'll perhaps be familiar with if you are used to application server clustering is a symmetric cluster.

With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured the same as every other node, and every node is connected to every other node in the cluster.

11.1.47. Temporary Queue

A simple example demonstrating how to use a JMS temporary queue.

11.1.48. Topic

A simple example demonstrating a JMS topic.

11.1.49. Topic Hierarchy

HornetQ supports topic hierarchies. With a topic hierarchy you can register a subscriber with a wild-card and that subscriber will receive any messages sent to an address that matches the wild card.

11.1.50. Topic Selector 1

The topic-selector-example1 example shows you how to send message to a JMS Topic, and subscribe them using selectors with HornetQ.

11.1.51. Topic Selector 2

The topic-selector-example1 example shows you how to selectively consume messages using message selectors with topic consumers.

11.1.52. Transactional Session

The transactional example shows you how to use a transactional Session with HornetQ.

11.1.53. XA Heuristic

The xa-heuristic example shows you how to make an XA heuristic decision through HornetQ Management Interface. A heuristic decision is a unilateral decision to commit or rollback an XA transaction branch after it has been prepared.

11.1.54. XA Receive

The xa-receive example shows you how message receiving behaves in an XA transaction in HornetQ.

11.1.55. XA Send

The xa-send example shows you how message sending behaves in an XA transaction in HornetQ.

11.1.56. XA with Transaction Manager

The xa-with-jta example shows you how to use JTA interfaces to control transactions with HornetQ.

11.2. Core API Examples

To run a core example, simply cd into the appropriate example directory and type ant

11.2.1. Embedded

This example shows how to embed the HornetQ server within your own code.

11.3. Java EE Examples

Most of the Java EE examples can be run the following way. simply cd into the appropriate example directory an type ant deploy. This will create a new JBoss AS profile and start the server. When the server is started from a different window type ant run to run the example. Some examples require further steps, please refer to the examples documentation for further instructions.

11.3.1. EJB/JMS Transaction

An example that shows using an EJB and JMS together within a transaction.

11.3.2. HAJNDI (High Availability)

A simple example demonstrating using JNDI within a cluster.

11.3.3. Resource Adapter Configuration

This example demonstrates how to configure several properties on the HornetQ JCA resource adaptor.

11.3.4. JMS Bridge

An example demonstrating the use of the HornetQ JMS bridge.

11.3.5. MDB (Message Driven Bean)

A simple example of a message driven bean.

11.3.6. Servlet Transport

An example of how to use the HornetQ servlet transport.

11.3.7. Servlet SSL Transport

An example of how to use the HornetQ servlet transport over SSL.

11.3.8. XA Recovery

An example of how XA recovery works within the JBoss Application server using HornetQ.