http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/examples.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/examples.xml b/docs/user-manual/en/examples.xml new file mode 100644 index 0000000..cec4021 --- /dev/null +++ b/docs/user-manual/en/examples.xml @@ -0,0 +1,689 @@ +<?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. --> +<!-- ============================================================================= --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> +%BOOK_ENTITIES; +]> +<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 WildFly + 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>mvn verify</literal> (For details please read the readme.html + in each example directory).</para> + <para>Here's a listing of the examples with a brief description.</para> + <section id="examples.aerogear"> + <title>JMS AeroGear</title> + <para>This example shows how you can send a message to a mobile device by leveraging + AeroGears push technology which provides support for different push notification technologies + like Google Cloud Messaging, Apple's APNs or Mozilla's SimplePush.</para> + </section> + <section id="examples.applet"> + <title>Applet</title> + <para>This example shows you how to send and receive JMS messages from an Applet.</para> + </section> + <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 failover listener</title> + <para>The <literal>client-side-failoverlistener</literal> example shows how to register a listener to monitor + failover events</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.durable"> + <title>Clustered Durable Subscription</title> + <para>This example demonstrates a clustered JMS durable subscription</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 id="examples.clustered.queue"> + <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 id="examples.clustered.jgroups"> + <title>Clustering with JGroups</title> + <para>The <literal>clustered-jgroups</literal> example demonstrates how to form a two + node cluster using JGroups as its underlying topology discovery technique, rather than + the default UDP broadcasting. 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 id="examples.clustered.standalone"> + <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 id="examples.clustered.static.discovery"> + <title>Clustered Static Discovery</title> + <para>This example demonstrates how to configure a cluster using a list of connectors rather + than UDP for discovery</para> + </section> + <section id="examples.clustered.static.oneway"> + <title>Clustered Static Cluster One Way</title> + <para>This example demonstrates how to set up a cluster where cluster connections are one way, + i.e. server A -> Server B -> Server C</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 id="examples.embedded.jms"> + <title>Embedded</title> + <para>The <literal>embedded</literal> example shows how to embed JMS + within your own code using POJO instantiation and no config files.</para> + </section> + <section id="examples.embedded.jms.simple"> + <title>Embedded Simple</title> + <para>The <literal>embedded</literal> example shows how to embed JMS within your own code using regular HornetQ XML files.</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.hornetq-ra-rar"> + <title>HornetQ Resource Adapter example</title> + <para>This examples shows how to build the hornetq resource adapters a rar for deployment in other Application + Server's</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.auto-closeable"> + <title>JMS Auto Closable</title> + <para>The <literal>jms-auto-closeable</literal> example shows how JMS resources, such + as connections, sessions and consumers, in JMS 2 can be automatically closed on error.</para> + </section> + <section id="examples.jms.completion-listener"> + <title>JMS Completion Listener</title> + <para>The <literal>jms-completion-listener</literal> example shows how to send a message + asynchronously to HornetQ and use a CompletionListener to be notified of the Broker + receiving it.</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.jms.jms-context"> + <title>JMS Context</title> + <para>The <literal>jms-context</literal> example shows how to send and receive a message + to a JMS Queue using HornetQ by using a JMS Context.</para> + <para>A JMSContext is part of JMS 2.0 and combines the JMS Connection and Session Objects + into a simple Interface.</para> + </section> + <section id="examples.jms.jms-shared-consumer"> + <title>JMS Shared Consumer</title> + <para>The <literal>jms-shared-consumer</literal> example shows you how can use shared + consumers to share a subscription on a topic. In JMS 1.1 this was not allowed and so caused + a scalability issue. In JMS 2 this restriction has been lifted so you can share the load + across different threads and connections.</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 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.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.multiple.failover"> + <title>Multiple Failover</title> + <para>This example demonstrates how to set up a live server with multiple backups</para> + </section> + <section id="examples.multiple.failover.failback"> + <title>Multiple Failover Failback</title> + <para>This example demonstrates how to set up a live server with multiple backups but + forcing failover back to the original live server</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 id="examples.proton-qpid"> + <title>Proton Qpid</title> + <para>HornetQ can be configured to accept requests from any AMQP client that supports the + 1.0 version of the protocol. This <literal>proton-j</literal> example shows a simply + qpid java 1.0 client example.</para> + </section> + <section id="examples.proton-ruby"> + <title>Proton Ruby</title> + <para>HornetQ can be configured to accept requests from any AMQP client that supports the + 1.0 version of the protocol. This example shows a simply proton ruby client + that sends and receives messages</para> + </section> + <section id="examples.queue"> + <title>Queue</title> + <para>A simple example demonstrating a JMS queue.</para> + </section> + <section id="examples.message-redistribution"> + <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 id="examples.queue-requestor"> + <title>Queue Requestor</title> + <para>A simple example demonstrating a JMS queue requestor.</para> + </section> + <section id="examples.queue-message-selector"> + <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 id="examples.reattach-node"> + <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 id="examples.replicated-failback"> + <title>Replicated Failback example</title> + <para>An example showing how failback works when using replication, In this example a live server will replicate + all its Journal to a backup server as it updates it. When the live server crashes the backup takes over + from the live server and the client reconnects and carries on from where it left off.</para> + </section> + <section id="examples.replicated-failback-static"> + <title>Replicated Failback static example</title> + <para>An example showing how failback works when using replication, but this time with static connectors</para> + </section> + <section id="examples.replicated-multiple-failover"> + <title>Replicated multiple failover example</title> + <para>An example showing how to configure multiple backups when using replication</para> + </section> + <section id="examples.replicated-failover-transaction"> + <title>Replicated Failover transaction example</title> + <para>An example showing how failover works with a transaction when using replication</para> + </section> + <section id="examples.request-reply"> + <title>Request-Reply example</title> + <para>A simple example showing the JMS request-response pattern.</para> + </section> + <section id="examples.rest"> + <title>Rest example</title> + <para>An example showing how to use the HornetQ Rest API</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 id="examples.security"> + <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 id="examples.jms.spring.integration"> + <title>Spring Integration</title> + <para>This example shows how to use embedded JMS using HornetQ's Spring integration.</para> + </section> + <section id="examples.ssl-transport"> + <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 id="examples.static-message-selector"> + <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 id="examples.static-message-selector-jms"> + <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 id="examples.stomp"> + <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 id="examples.stomp1.1"> + <title>Stomp1.1</title> + <para>The <literal>stomp</literal> example shows you how to configure a + HornetQ server to send and receive Stomp messages via a Stomp 1.1 connection.</para> + </section> + <section id="examples.stomp1.2"> + <title>Stomp1.2</title> + <para>The <literal>stomp</literal> example shows you how to configure a + HornetQ server to send and receive Stomp messages via a Stomp 1.2 connection.</para> + </section> + <section id="examples.stomp-web-socket"> + <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 id="examples.symmetric-cluster"> + <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 id="examples.temporary-queue"> + <title>Temporary Queue</title> + <para>A simple example demonstrating how to use a JMS temporary queue.</para> + </section> + <section id="examples.topic"> + <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 id="examples.topic-selector-1"> + <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 id="examples.topic-selector-2"> + <title>Topic Selector 2</title> + <para>The <literal>topic-selector-example2</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</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 sharing of a journal between the + servers. When 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 id="examples.no-transaction-failover"> + <title>Failover Without Transactions</title> + <para>The <literal>stop-server-failover</literal> example demonstrates failover of the + JMS connection from one node to another when the live server crashes using a JMS + non-transacted session.</para> + </section> + <section id="examples.transactional-session"> + <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>The <literal>embedded</literal> 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 navigate into the + appropriate example directory and type <literal>mvn verify</literal>. This will use Arquillian to run the Application + Server and deploy the application. Note that you must have WildFly installed and the JBOSS_HOME environment + variable set. Please refer to the examples documentation for further instructions.</para> + <note> + <para>When running the Java EE examples you may see warning messages in the WildFly log about incompatible client and + server versions. This is normal if a newer version of the HornetQ project is being used with a version of WildFly that + ships an older version of HornetQ. These examples should still complete without any functional errors.</para> + </note> + <section> + <title>EJB/JMS Transaction</title> + <para>An example that shows using an EJB and JMS together within a transaction.</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> + <title>Resource Adapter Remote Server Configuration</title> + <para>This example demonstrates how to configure the HornetQ resource adapter to talk to a remote HornetQ server</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 set of examples of message driven beans, including failover examples.</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>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/filter-expressions.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/filter-expressions.xml b/docs/user-manual/en/filter-expressions.xml new file mode 100644 index 0000000..2cf7bd2 --- /dev/null +++ b/docs/user-manual/en/filter-expressions.xml @@ -0,0 +1,87 @@ +<?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. --> +<!-- ============================================================================= --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> +%BOOK_ENTITIES; +]> + +<chapter id="filter-expressions"> + <title>Filter Expressions</title> + <para>HornetQ provides a powerful filter language based on a subset of the SQL 92 + expression syntax.</para> + <para>It is the same as the syntax used for JMS selectors, but the predefined identifiers are + different. For documentation on JMS selector syntax please the JMS javadoc for <ulink + url="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html"; + >javax.jms.Message</ulink>.</para> + <para>Filter expressions are used in several places in HornetQ</para> + <itemizedlist> + <listitem> + <para>Predefined Queues. When pre-defining a queue, either in <literal + >hornetq-configuration.xml</literal> or <literal>hornetq-jms.xml</literal> a filter + expression can be defined for a queue. Only messages that match the filter + expression will enter the queue.</para> + </listitem> + <listitem> + <para>Core bridges can be defined with an optional filter expression, only matching + messages will be bridged (see <xref linkend="core-bridges"/>).</para> + </listitem> + <listitem> + <para>Diverts can be defined with an optional filter expression, only matching messages + will be diverted (see <xref linkend="diverts" />).</para> + </listitem> + <listitem> + <para>Filter are also used programmatically when creating consumers, queues and in + several places as described in <xref linkend="management"/>.</para> + </listitem> + </itemizedlist> + <para>There are some differences between JMS selector expressions and HornetQ core + filter expressions. Whereas JMS selector expressions operate on a JMS message, HornetQ + core filter expressions operate on a core message.</para> + <para>The following identifiers can be used in a core filter expressions to refer to attributes + of the core message in an expression:</para> + <itemizedlist> + <listitem> + <para><literal>HQPriority</literal>. To refer to the priority of a message. Message + priorities are integers with valid values from <literal>0 - 9</literal>. <literal + >0</literal> is the lowest priority and <literal>9</literal> is the highest. + E.g. <literal>HQPriority = 3 AND animal = 'aardvark'</literal></para> + </listitem> + <listitem> + <para><literal>HQExpiration</literal>. To refer to the expiration time of a message. + The value is a long integer.</para> + </listitem> + <listitem> + <para><literal>HQDurable</literal>. To refer to whether a message is durable or not. + The value is a string with valid values: <literal>DURABLE</literal> or <literal + >NON_DURABLE</literal>.</para> + </listitem> + <listitem> + <para><literal>HQTimestamp</literal>. The timestamp of when the message was created. + The value is a long integer.</para> + </listitem> + <listitem> + <para><literal>HQSize</literal>. The size of a message in bytes. The value is an + integer.</para> + </listitem> + </itemizedlist> + <para>Any other identifiers used in core filter expressions will be assumed to be properties of + the message.</para> +</chapter> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/flow-control.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/flow-control.xml b/docs/user-manual/en/flow-control.xml new file mode 100644 index 0000000..0de8276 --- /dev/null +++ b/docs/user-manual/en/flow-control.xml @@ -0,0 +1,316 @@ +<?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. --> +<!-- ============================================================================= --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> +%BOOK_ENTITIES; +]> +<chapter id="flow-control"> + <title>Flow Control</title> + <para>Flow control is used to limit the flow of data between a client and server, or a server and + another server in order to prevent the client or server being overwhelmed with data.</para> + <section> + <title>Consumer Flow Control</title> + <para>This controls the flow of data between the server and the client as the client consumes + messages. For performance reasons clients normally buffer messages before delivering to the + consumer via the <literal>receive()</literal> method or asynchronously via a message + listener. If the consumer cannot process messages as fast as they are being delivered and + stored in the internal buffer, then you could end up with a situation where messages would + keep building up possibly causing out of memory on the client if they cannot be processed + in time.</para> + <section id="flow-control.consumer.window"> + <title>Window-Based Flow Control</title> + <para>By default, HornetQ consumers buffer messages from the server in a client side buffer + before the client consumes them. This improves performance: otherwise every time the + client consumes a message, HornetQ would have to go the server to request the next + message. In turn, this message would then get sent to the client side, if one was + available.</para> + <para>A network round trip would be involved for <emphasis>every</emphasis> message and + considerably reduce performance.</para> + <para>To prevent this, HornetQ pre-fetches messages into a buffer on each consumer. The + total maximum size of messages (in bytes) that will be buffered on each consumer is + determined by the <literal>consumer-window-size</literal> parameter.</para> + <para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024 + bytes).</para> + <para>The value can be:</para> + <itemizedlist> + <listitem> + <para><literal>-1</literal> for an <emphasis>unbounded</emphasis> buffer</para> + </listitem> + <listitem> + <para><literal>0</literal> to not buffer any messages. See <xref + linkend="examples.no-consumer-buffering"/> for working example of a consumer + with no buffering.</para> + </listitem> + <listitem> + <para><literal>>0</literal> for a buffer with the given maximum size in + bytes.</para> + </listitem> + </itemizedlist> + <para>Setting the consumer window size can considerably improve performance depending on + the messaging use case. As an example, let's consider the two extremes: </para> + <variablelist> + <varlistentry> + <term>Fast consumers</term> + <listitem> + <para>Fast consumers can process messages as fast as they consume them (or even + faster)</para> + <para>To allow fast consumers, set the <literal>consumer-window-size</literal> to + -1. This will allow <emphasis>unbounded</emphasis> message buffering on the + client side.</para> + <para>Use this setting with caution: it can overflow the client memory if the + consumer is not able to process messages as fast as it receives them.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Slow consumers</term> + <listitem> + <para>Slow consumers takes significant time to process each message and it is + desirable to prevent buffering messages on the client side so that they can be + delivered to another consumer instead.</para> + <para>Consider a situation where a queue has 2 consumers; 1 of which is very slow. + Messages are delivered in a round robin fashion to both consumers, the fast + consumer processes all of its messages very quickly until its buffer is empty. + At this point there are still messages awaiting to be processed in the buffer + of the slow consumer thus preventing them being processed by the fast consumer. + The fast consumer is therefore sitting idle when it could be processing the + other messages. </para> + <para>To allow slow consumers, set the <literal>consumer-window-size</literal> to + 0 (for no buffer at all). This will prevent the slow consumer from buffering + any messages on the client side. Messages will remain on the server side ready + to be consumed by other consumers.</para> + <para>Setting this to 0 can give deterministic distribution between multiple + consumers on a queue.</para> + </listitem> + </varlistentry> + </variablelist> + <para>Most of the consumers cannot be clearly identified as fast or slow consumers but are + in-between. In that case, setting the value of <literal>consumer-window-size</literal> + to optimize performance depends on the messaging use case and requires benchmarks to + find the optimal value, but a value of 1MiB is fine in most cases.</para> + <section id="flow-control.core.api"> + <title>Using Core API</title> + <para>If HornetQ Core API is used, the consumer window size is specified by <literal + >ServerLocator.setConsumerWindowSize()</literal> method and some of the + <literal>ClientSession.createConsumer()</literal> methods.</para> + </section> + <section> + <title>Using JMS</title> + <para>if JNDI is used to look up the connection factory, the consumer window size is + configured in <literal>hornetq-jms.xml</literal>:</para> + <programlisting> +<connection-factory name="ConnectionFactory"> + <connectors> + <connector-ref connector-name="netty-connector"/> + </connectors> + <entries> + <entry name="ConnectionFactory"/> + </entries> + + <!-- Set the consumer window size to 0 to have *no* buffer on the client side --> + <consumer-window-size>0</consumer-window-size> +</connection-factory></programlisting> + <para>If the connection factory is directly instantiated, the consumer window size is + specified by <literal>HornetQConnectionFactory.setConsumerWindowSize()</literal> + method.</para> + <para>Please see <xref linkend="examples.no-consumer-buffering"/> for an example which + shows how to configure HornetQ to prevent consumer buffering when dealing with slow + consumers.</para> + </section> + </section> + <section> + <title>Rate limited flow control</title> + <para>It is also possible to control the <emphasis>rate</emphasis> at which a consumer can + consume messages. This is a form of throttling and can be used to make sure that a + consumer never consumes messages at a rate faster than the rate specified. </para> + <para>The rate must be a positive integer to enable this functionality and is the maximum + desired message consumption rate specified in units of messages per second. Setting this + to <literal>-1</literal> disables rate limited flow control. The default value is + <literal>-1</literal>.</para> + <para>Please see <xref linkend="examples.consumer-rate-limit"/> for a working example of + limiting consumer rate.</para> + <section id="flow-control.rate.core.api"> + <title>Using Core API</title> + <para>If the HornetQ core API is being used the rate can be set via the <literal + >ServerLocator.setConsumerMaxRate(int consumerMaxRate)</literal> method or + alternatively via some of the <literal>ClientSession.createConsumer()</literal> + methods. </para> + </section> + <section> + <title>Using JMS</title> + <para>If JNDI is used to look up the connection factory, the max rate can be configured + in <literal>hornetq-jms.xml</literal>:</para> + <programlisting> +<connection-factory name="ConnectionFactory"> + <connectors> + <connector-ref connector-name="netty-connector"/> + </connectors> + <entries> + <entry name="ConnectionFactory"/> + </entries> + <!-- We limit consumers created on this connection factory to consume messages at a maximum rate + of 10 messages per sec --> + <consumer-max-rate>10</consumer-max-rate> +</connection-factory></programlisting> + <para>If the connection factory is directly instantiated, the max rate size can be set + via the <literal>HornetQConnectionFactory.setConsumerMaxRate(int + consumerMaxRate)</literal> method.</para> + <note> + <para>Rate limited flow control can be used in conjunction with window based flow + control. Rate limited flow control only effects how many messages a client can + consume in a second and not how many messages are in its buffer. So if you had a + slow rate limit and a high window based limit the clients internal buffer would + soon fill up with messages.</para> + </note> + <para>Please see <xref linkend="examples.consumer-rate-limit"/> for an example which + shows how to configure HornetQ to prevent consumer buffering when dealing with slow + consumers.</para> + </section> + </section> + </section> + <section> + <title>Producer flow control</title> + <para>HornetQ also can limit the amount of data sent from a client to a server to prevent the + server being overwhelmed.</para> + <section> + <title>Window based flow control</title> + <para>In a similar way to consumer window based flow control, HornetQ producers, by + default, can only send messages to an address as long as they have sufficient credits to + do so. The amount of credits required to send a message is given by the size of the + message.</para> + <para>As producers run low on credits they request more from the server, when the server + sends them more credits they can send more messages.</para> + <para>The amount of credits a producer requests in one go is known as the <emphasis + role="italic">window size</emphasis>.</para> + <para>The window size therefore determines the amount of bytes that can be in-flight at any + one time before more need to be requested - this prevents the remoting connection from + getting overloaded.</para> + <section> + <title>Using Core API</title> + <para>If the HornetQ core API is being used, window size can be set via the <literal + >ServerLocator.setProducerWindowSize(int producerWindowSize)</literal> + method.</para> + </section> + <section> + <title>Using JMS</title> + <para>If JNDI is used to look up the connection factory, the producer window size can be + configured in <literal>hornetq-jms.xml</literal>:</para> + <programlisting> +<connection-factory name="ConnectionFactory"> + <connectors> + <connector-ref connector-name="netty-connector"/> + </connectors> + <entries> + <entry name="ConnectionFactory"/> + </entries> + <producer-window-size>10</producer-window-size> +</connection-factory></programlisting> + <para>If the connection factory is directly instantiated, the producer window size can + be set via the <literal>HornetQConnectionFactory.setProducerWindowSize(int + producerWindowSize)</literal> method.</para> + </section> + <section> + <title>Blocking producer window based flow control</title> + <para>Normally the server will always give the same number of credits as have been + requested. However, it is also possible to set a maximum size on any address, and the + server will never send more credits than could cause the address's upper memory limit + to be exceeded.</para> + <para>For example, if I have a JMS queue called "myqueue", I could set the maximum + memory size to 10MiB, and the the server will control the number of credits sent to + any producers which are sending any messages to myqueue such that the total messages + in the queue never exceeds 10MiB.</para> + <para>When the address gets full, producers will block on the client side until more + space frees up on the address, i.e. until messages are consumed from the queue thus + freeing up space for more messages to be sent.</para> + <para>We call this blocking producer flow control, and it's an efficient way to prevent + the server running out of memory due to producers sending more messages than can be + handled at any time.</para> + <para>It is an alternative approach to paging, which does not block producers but + instead pages messages to storage.</para> + <para>To configure an address with a maximum size and tell the server that you want to + block producers for this address if it becomes full, you need to define an + AddressSettings (<xref linkend="queue-attributes.address-settings"/>) block for the + address and specify <literal>max-size-bytes</literal> and <literal + >address-full-policy</literal></para> + <para>The address block applies to all queues registered to that address. I.e. the total + memory for all queues bound to that address will not exceed <literal + >max-size-bytes</literal>. In the case of JMS topics this means the <emphasis + role="italic">total</emphasis> memory of all subscriptions in the topic won't + exceed max-size-bytes.</para> + <para>Here's an example:</para> + <programlisting> +<address-settings> + <address-setting match="jms.queue.exampleQueue"> + <max-size-bytes>100000</max-size-bytes> + <address-full-policy>BLOCK</address-full-policy> + </address-setting> +</address-settings></programlisting> + <para>The above example would set the max size of the JMS queue "exampleQueue" to be + 100000 bytes and would block any producers sending to that address to prevent that + max size being exceeded.</para> + <para>Note the policy must be set to <literal>BLOCK</literal> to enable blocking producer + flow control.</para> + <note><para>Note that in the default configuration all addresses are set to block producers after 10 MiB of message data + is in the address. This means you cannot send more than 10MiB of message data to an address without it being consumed before the producers + will be blocked. If you do not want this behaviour increase the <literal>max-size-bytes</literal> parameter or change the + address full message policy.</para> + </note> + </section> + </section> + <section> + <title>Rate limited flow control</title> + <para>HornetQ also allows the rate a producer can emit message to be limited, in units of + messages per second. By specifying such a rate, HornetQ will ensure that producer never + produces messages at a rate higher than that specified.</para> + <para>The rate must be a positive integer to enable this functionality and is the maximum + desired message consumption rate specified in units of messages per second. Setting this + to <literal>-1</literal> disables rate limited flow control. The default value is + <literal>-1</literal>.</para> + <para>Please see the <xref linkend="producer-rate-limiting-example"/> for a working example + of limiting producer rate.</para> + <section id="flow-control.producer.rate.core.api"> + <title>Using Core API</title> + <para>If the HornetQ core API is being used the rate can be set via the <literal + >ServerLocator.setProducerMaxRate(int consumerMaxRate)</literal> method or + alternatively via some of the <literal>ClientSession.createProducer()</literal> + methods. </para> + </section> + <section> + <title>Using JMS</title> + <para>If JNDI is used to look up the connection factory, the max rate can be configured + in <literal>hornetq-jms.xml</literal>:</para> + <programlisting> +<connection-factory name="ConnectionFactory"> + <connectors> + <connector-ref connector-name="netty-connector"/> + </connectors> + <entries> + <entry name="ConnectionFactory"/> + </entries> + <!-- We limit producers created on this connection factory to produce messages at a maximum rate + of 10 messages per sec --> + <producer-max-rate>10</producer-max-rate> +</connection-factory></programlisting> + <para>If the connection factory is directly instantiated, the max rate size can be set + via the <literal>HornetQConnectionFactory.setProducerMaxRate(int + consumerMaxRate)</literal> method.</para> + </section> + </section> + </section> +</chapter>
