examples.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
<!--                                                                               -->
<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
<!--                                                                               -->
<!-- An explanation of CC-BY-SA is available at                                    -->
<!--                                                                               -->
<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
<!--                                                                               -->
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
<!-- of it, you must provide the URL for the original version.                     -->
<!--                                                                               -->
<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
<!-- permitted by applicable law.                                                  -->
<!-- ============================================================================= -->
<chapter id="examples">
    <title>Examples</title>
    <para>The HornetQ distribution comes with over 70 run out-of-the-box examples demonstrating many
        of the features.</para>
    <para>The examples are available in the distribution, in the <literal>examples</literal>
        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.</para>
    <para>A set of Java EE examples are also provided which need the JBoss Application Server
        installed to be able to run.</para>
    <section>
        <title>JMS Examples</title>
        <para>To run a JMS example, simply <literal>cd</literal> into the appropriate example
            directory and type <literal>./build.sh</literal> (or <literal>build.bat</literal> if you
            are on Windows).</para>
        <para>Here's a listing of the examples with a brief description.</para>
        <section id="application-level-failover">
            <title>Application-Layer Failover</title>
            <para>HornetQ also supports Application-Layer failover, useful in the case that
                replication is not enabled on the server side.</para>
            <para>With Application-Layer failover, it's up to the application to register a JMS
                    <literal>ExceptionListener</literal> with HornetQ which will be called by
                HornetQ in the event that connection failure is detected.</para>
            <para>The code in the <literal>ExceptionListener</literal> then recreates the JMS
                connection, session, etc on another node and the application can continue.</para>
            <para>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.</para>
        </section>
        <section id="examples.bridge">
            <title>Core Bridge Example</title>
            <para>The <literal>bridge</literal> 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.</para>
            <para>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.</para>
        </section>
        <section id="examples.browsers">
            <title>Browser</title>
            <para>The <literal>browser</literal> example shows you how to use a JMS <literal
                    >QueueBrowser</literal> with HornetQ.</para>
            <para>Queues are a standard part of JMS, please consult the JMS 1.1 specification for
                full details.</para>
            <para> A <literal>QueueBrowser</literal> 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.</para>
        </section>
        <section>
            <title>Client Kickoff</title>
            <para>The <literal>client-kickoff</literal> example shows how to terminate client
                connections given an IP address using the JMX management API.</para>
        </section>
        <section>
            <title>Client-Side Load-Balancing</title>
            <para>The <literal>client-side-load-balancing</literal> example demonstrates how
                sessions created from a single JMS <literal>Connection</literal> can
                be created to different nodes of the cluster. In other words it demonstrates how
                HornetQ does client-side load-balancing of sessions across the cluster.</para>
        </section>
        <section id="examples.clustered.grouping">
            <title>Clustered Grouping</title>
            <para>This is similar to the message grouping example except that it demonstrates it
                working over a cluster. Messages sent to different nodes with the same group id will
                be sent to the same node and the same consumer.</para>
        </section>
        <section>
            <title>Clustered Queue</title>
            <para>The <literal>clustered-queue</literal> 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.</para>
        </section>
        <section>
            <title>Clustered Standalone</title>
            <para>The <literal>clustered-standalone</literal> 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.</para>
        </section>
        <section>
            <title>Clustered Topic</title>
            <para>The <literal>clustered-topic</literal> 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.</para>
        </section>
        <section id="examples.consumer-rate-limit">
            <title>Message Consumer Rate Limiting</title>
            <para>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.</para>
            <para>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.</para>
        </section>
        <section id="examples.dead-letter">
            <title>Dead Letter</title>
            <para>The <literal>dead-letter</literal> 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). </para>
            <para>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.</para>
            <para>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.</para>
        </section>
        <section id="examples.delayed-redelivery">
            <title>Delayed Redelivery</title>
            <para>The <literal>delayed-redelivery</literal> example demonstrates how HornetQ can be
                configured to provide a delayed redelivery in the case a message needs to be
                redelivered.</para>
            <para>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.</para>
        </section>
        <section id="divert-example">
            <title>Divert</title>
            <para>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.</para>
        </section>
        <section>
            <title>Durable Subscription</title>
            <para>The <literal>durable-subscription</literal> 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.</para>
            <para>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 durable messages. </para>
        </section>
        <section>
            <title>Embedded</title>
            <para>The <literal>embedded</literal> example shows how to embed the HornetQ server
                within your own code.</para>
        </section>
        <section>
            <title>HTTP Transport</title>
            <para>The <literal>http-transport</literal> example shows you how to configure HornetQ
                to use the HTTP protocol as its transport layer.</para>
        </section>
        <section>
            <title>Instantiate JMS Objects Directly</title>
            <para>Usually, JMS Objects such as <literal>ConnectionFactory</literal>, <literal
                    >Queue</literal> and <literal>Topic</literal> instances are looked up from JNDI
                before being used by the client code. This objects are called "administered objects"
                in JMS terminology.</para>
            <para>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.</para>
        </section>
        <section id="examples.interceptor">
            <title>Interceptor</title>
            <para>HornetQ allows an application to use an interceptor to hook into the messaging
                system. Interceptors allow you to handle various message events in HornetQ.</para>
        </section>
        <section id="examples.jaas">
            <title>JAAS</title>
            <para>The <literal>jaas</literal> 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.</para>
        </section>
        <section id="examples.jms.jms-bridge">
            <title>JMS Bridge</title>
            <para>The <literal>jms-brige</literal> example shows how to setup a bridge
            between two standalone HornetQ servers.</para>
        </section>
        <section id="examples.jmx">
            <title>JMX Management</title>
            <para>The <literal>jmx</literal> example shows how to manage HornetQ using JMX.</para>
        </section>
        <section id="examples.large-message">
            <title>Large Message</title>
            <para>The <literal>large-message</literal> 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.</para>
            <para>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.</para>
        </section>
        <section id="examples.last-value-queue">
            <title>Last-Value Queue</title>
            <para>The <literal>last-value-queue</literal> 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.</para>
            <para>A typical example for last-value queue is for stock prices, where you are only
                interested by the latest price for a particular stock.</para>
        </section>
        <section>
            <title>Load Balanced Clustered Queue</title>
            <para>The <literal>clustered-queue</literal> example demonstrates a JMS queue deployed
                on two different nodes. The two nodes are configured to form a cluster.</para>
            <para>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.</para>
            <para>In other words, HornetQ load balances the sent messages across all consumers on
                the cluster</para>
        </section>
        <section id="examples.management">
            <title>Management</title>
            <para>The <literal>management</literal> example shows how to manage HornetQ using JMS
                Messages to invoke management operations on the server.</para>
        </section>
        <section id="examples.management-notifications">
            <title>Management Notification</title>
            <para>The <literal>management-notification</literal> 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, addresses are created or deleted, security authentication fails,
                etc.).</para>
        </section>
        <section id="examples.message-counters">
            <title>Message Counter</title>
            <para>The <literal>message-counters</literal> example shows you how to use message
                counters to obtain message information for a JMS queue.</para>
        </section>
        <section id="examples.expiry">
            <title>Message Expiration</title>
            <para>The <literal>expiry</literal> 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).</para>
            <para>HornetQ can assign an expiry address to a given queue so that when messages
                are expired, they are removed from the queue and sent to the expiry address.
                These "expired" messages can later be consumed from the expiry address for
                further inspection.</para>
        </section>
        <section id="examples.message-group">
            <title>Message Group</title>
            <para>The <literal>message-group</literal> 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:</para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>Messages in a message group share the same group id, i.e. they have
                            same JMSXGroupID string property values</para>
                    </listitem>
                    <listitem>
                        <para>The consumer that receives the first message of a group will receive
                            all the messages that belongs to the group</para>
                    </listitem>
                </itemizedlist>
            </para>
        </section>
       <section id="examples.message-group2">
            <title>Message Group</title>
            <para>The <literal>message-group2</literal> example shows you how to configure and use
                message groups with HornetQ via a connection factory.</para>
        </section>
        <section id="examples.message-priority">
            <title>Message Priority</title>
            <para>Message Priority can be used to influence the delivery order for messages.</para>
            <para>It can be retrieved by the message's standard header field 'JMSPriority' as
                defined in JMS specification version 1.1. </para>
            <para>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. </para>
            <para>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.</para>
        </section>
        <section id="examples.no-consumer-buffering">
            <title>No Consumer Buffering</title>
            <para>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 <literal>MessageListener onMessage()</literal> 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.</para>
            <para>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.</para>
            <para>In some case buffering is not desirable, and HornetQ allows it to be switched off.
                This example demonstrates that.</para>
        </section>
        <section id="examples.non-transaction-failover">
            <title>Non-Transaction Failover With Server Data Replication</title>
            <para>The <literal>non-transaction-failover</literal> example demonstrates two servers coupled
                as a live-backup pair for high availability (HA), and a client using a <emphasis>non-transacted
                </emphasis> JMS session failing over from live to backup when the live server is
                crashed.</para>
            <para>HornetQ implements 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 and continue to send and consume messages. When non-transacted
                 sessions are used, once and only once message delivery is not guaranteed and it is possible
                 that some messages will be lost or delivered twice.</para>
        </section>
        <section id="examples.paging">
            <title>Paging</title>
            <para>The <literal>paging</literal> example shows how HornetQ can support huge queues
                even when the server is running in limited RAM. It does this by transparently
                    <emphasis>paging</emphasis> messages to disk, and <emphasis>depaging</emphasis>
                them when they are required.</para>
        </section>
        <section id="examples.pre-acknowledge">
            <title>Pre-Acknowledge</title>
            <para>Standard JMS supports three acknowledgement modes:<literal>
                    AUTO_ACKNOWLEDGE</literal>, <literal>CLIENT_ACKNOWLEDGE</literal>, and <literal
                    >DUPS_OK_ACKNOWLEDGE</literal>. For a full description on these modes please
                consult the JMS specification, or any JMS tutorial.</para>
            <para>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.</para>
        </section>
        <section id="producer-rate-limiting-example">
            <title>Message Producer Rate Limiting</title>
            <para>The <literal>producer-rte-limit</literal> example demonstrates how, with HornetQ,
                you can specify a maximum send rate at which a JMS message producer will send
                messages.</para>
        </section>
        <section>
            <title>Queue</title>
            <para>A simple example demonstrating a JMS queue.</para>
        </section>
        <section>
            <title>Message Redistribution</title>
            <para>The <literal>queue-message-redistribution</literal> example demonstrates message
                redistribution between queues with the same name deployed in different nodes of a
                cluster.</para>
        </section>
        <section>
            <title>Queue Requestor</title>
            <para>A simple example demonstrating a JMS queue requestor.</para>
        </section>
        <section>
            <title>Queue with Message Selector</title>
            <para>The <literal>queue-selector</literal> example shows you how to selectively consume
                messages using message selectors with queue consumers.</para>
        </section>
        <section>
            <title>Reattach Node example</title>
            <para>The <literal>Reattach Node</literal> example shows how a client can try to reconnect to
               the same server instead of failing the connection immediately and
               notifying any user ExceptionListener objects. HornetQ can be configured to automatically
               retry the connection, and reattach to the server when it becomes available again across
               the network.</para>
        </section>
        <section>
            <title>Request-Reply example</title>
            <para>A simple example showing the JMS request-response pattern.</para>
        </section>
        <section id="examples.scheduled-message">
            <title>Scheduled Message</title>
            <para>The <literal>scheduled-message</literal> 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.</para>
        </section>
        <section>
            <title>Security</title>
            <para>The <literal>security</literal> example shows you how configure and use role based
                queue security with HornetQ.</para>
        </section>
        <section id="asynchronous-send-acknowledgements-example">
            <title>Send Acknowledgements</title>
            <para>The <literal>send-acknowledgements</literal> example shows you how to use
                HornetQ's advanced <emphasis>asynchronous send acknowledgements</emphasis> feature
                to obtain acknowledgement from the server that sends have been received and
                processed in a separate stream to the sent messages. </para>
        </section>
        <section>
            <title>SSL Transport</title>
            <para>The <literal>ssl-enabled</literal> shows you how to configure SSL with HornetQ to
                send and receive message.</para>
        </section>
        <section>
            <title>Static Message Selector</title>
            <para>The <literal>static-selector</literal> example shows you how to configure a
                HornetQ core queue with static message selectors (filters).</para>
        </section>
        <section>
            <title>Static Message Selector Using JMS</title>
            <para>The <literal>static-selector-jms</literal> example shows you how to configure a
                HornetQ queue with static message selectors (filters) using JMS.</para>
        </section>
        <section>
            <title>Stomp</title>
            <para>The <literal>stomp</literal> example shows you how to configure a
                HornetQ server to send and receive Stomp messages.</para>
        </section>
        <section>
            <title>Stomp Over Web Sockets</title>
            <para>The <literal>stomp-websockets</literal> example shows you how to configure a
                HornetQ server to send and receive Stomp messages directly from Web browsers (provided
                they support Web Sockets).</para>
        </section>
        <section>
            <title>Symmetric Cluster</title>
            <para>The <literal>symmetric-cluster</literal> example demonstrates a symmetric cluster
                set-up with HornetQ.</para>
            <para>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.</para>
            <para>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.</para>
        </section>
        <section>
            <title>Temporary Queue</title>
            <para>A simple example demonstrating how to use a JMS temporary queue.</para>
        </section>
        <section>
            <title>Topic</title>
            <para>A simple example demonstrating a JMS topic.</para>
        </section>
        <section id="topic-hierarchy-example">
            <title>Topic Hierarchy</title>
            <para>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.</para>
        </section>
        <section>
            <title>Topic Selector 1</title>
            <para>The <literal>topic-selector-example1</literal> example shows you how to send
                message to a JMS Topic, and subscribe them using selectors with HornetQ.</para>
        </section>
        <section>
            <title>Topic Selector 2</title>
            <para>The <literal>topic-selector-example1</literal> example shows you how to
                selectively consume messages using message selectors with topic consumers.</para>
        </section>
        <section id="examples.transaction-failover">
            <title>Transaction Failover With Data Replication</title>
            <para>The <literal>transaction-failover</literal> example demonstrates two servers coupled
                as a live-backup pair for high availability (HA), and a client using a transacted JMS
                session failing over from live to backup when the live server is
                crashed.</para>
            <para>HornetQ implements failover of client connections between
                live and backup servers. This is implemented by the replication of data between
                live and backup nodes. When replication is configured and a live node crashes, the
                client connections can carry and continue to send and consume messages. When transacted
                sessions are used, once and only once message delivery is guaranteed.</para>
        </section>
        <section>
            <title>Transactional Session</title>
            <para>The <literal>transactional</literal> example shows you how to use a transactional
                Session with HornetQ.</para>
        </section>
        <section>
            <title>XA Heuristic</title>
            <para>The <literal>xa-heuristic</literal> 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.</para>
        </section>
        <section>
            <title>XA Receive</title>
            <para>The <literal>xa-receive</literal> example shows you how message receiving behaves
                in an XA transaction in HornetQ.</para>
        </section>
        <section>
            <title>XA Send</title>
            <para>The <literal>xa-send</literal> example shows you how message sending behaves in an
                XA transaction in HornetQ.</para>
        </section>
        <section>
            <title>XA with Transaction Manager</title>
            <para>The <literal>xa-with-jta</literal> example shows you how to use JTA interfaces to
                control transactions with HornetQ.</para>
        </section>
    </section>
    <section>
        <title>Core API Examples</title>
        <para>To run a core example, simply <literal>cd</literal> into the appropriate example
            directory and type <literal>ant</literal></para>
        <section id="examples.embedded">
            <title>Embedded</title>
            <para>This example shows how to embed the HornetQ server within your own code.</para>
        </section>
    </section>
    <section>
        <title>Java EE Examples</title>
        <para>Most of the Java EE examples can be run the following way. simply cd into the
            appropriate example directory an type <literal>ant deploy</literal>. This will create a
            new JBoss AS profile and start the server. When the server is started from a different
            window type <literal>ant run</literal> to run the example. Some examples require further
            steps, please refer to the examples documentation for further instructions.</para>
        <section>
            <title>EJB/JMS Transaction</title>
            <para>An example that shows using an EJB and JMS together within a transaction.</para>
        </section>
        <section>
            <title>HAJNDI (High Availability)</title>
            <para>A simple example demonstrating using JNDI within a cluster.</para>
        </section>
        <section>
            <title>Resource Adapter Configuration</title>
            <para>This example demonstrates how to configure several properties on the HornetQ JCA
                resource adaptor.</para>
        </section>
        <section id="examples.javaee.jms-bridge">
            <title>JMS Bridge</title>
            <para>An example demonstrating the use of the HornetQ JMS bridge.</para>
        </section>
        <section>
            <title>MDB (Message Driven Bean)</title>
            <para>A simple example of a message driven bean.</para>
        </section>
        <section>
            <title>Servlet Transport</title>
            <para>An example of how to use the HornetQ servlet transport.</para>
        </section>
        <section>
            <title>Servlet SSL Transport</title>
            <para>An example of how to use the HornetQ servlet transport over SSL.</para>
        </section>
        <section id="xa-recovery-example">
            <title>XA Recovery</title>
            <para>An example of how XA recovery works within the JBoss Application server using
                HornetQ.</para>
        </section>
    </section>
</chapter>