stomp-manual.html - activemq-web - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
   Architecture
 -->
 <html lang="en">
   <head>
     <meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
     <meta content="ActiveMQ's next generation of messaging" name="description"/>
     <meta content="messaging,stomp,jms,activemq,apollo" name="keywords"/>
     <meta content="Apollo" name="author"/>
     <script src="../scripts/jquery.js"></script>
     <link type="text/css" rel="stylesheet" href="../styles/impact/css/pygmentize.css"/>
     <link type="text/css" rel="stylesheet" href="../styles/impact/css/site.css"/>
     <title></title>
   </head>
   <body>
     <div id="navigation">
       <div class="wrapper">
 <ul>
 <li><a href="../index.html">Apollo 1.7.1</a></li>
 <li><a href="../community/developers.html">Developers</a></li>
 <li><a href="../community/index.html">Community</a></li>
 <li><a href="../download.html">Download</a></li>
 </ul>        <div></div>
       </div>
     </div>
     <div id="content">
       <div class="wrapper">
 <h1 id = "Apollo_1_7_1_STOMP_Protocol_Manual">Apollo 1.7.1 STOMP Protocol Manual</h1>

 <p><div class="toc"><ul style="list-style:none;">
   <li><a href="#Using_the_STOMP_Protocol">Using the STOMP Protocol</a></li>
   <li><ul style="list-style:none;">
     <li><a href="#Stomp_Protocol_Options">Stomp Protocol Options</a></li>
     <li><a href="#Client_Libraries">Client Libraries</a></li>
     <li><a href="#Connecting">Connecting</a></li>
     <li><a href="#Destination_Types">Destination Types</a></li>
     <li><a href="#Topic_Retained_Messages">Topic Retained Messages</a></li>
     <li><a href="#Reliable_Messaging">Reliable Messaging</a></li>
     <li><a href="#Message_Expiration">Message Expiration</a></li>
     <li><a href="#Subscription_Flow_Control">Subscription Flow Control</a></li>
     <li><a href="#Topic_Durable_Subscriptions">Topic Durable Subscriptions</a></li>
     <li><a href="#Browsing_Subscriptions">Browsing Subscriptions</a></li>
     <li><a href="#Queue_Message_Sequences">Queue Message Sequences</a></li>
     <li><a href="#Using_Queue_Browsers_to_Implement_Durable_Topic_Subscriptions">Using Queue Browsers to Implement Durable Topic Subscriptions</a></li>
     <li><a href="#Exclusive_Subscriptions">Exclusive Subscriptions</a></li>
     <li><a href="#Message_Groups">Message Groups</a></li>
     <li><a href="#Temporary_Destinations">Temporary Destinations</a></li>
     <li><a href="#Destination_Wildcards">Destination Wildcards</a></li>
     <li><a href="#Composite_Destinations">Composite Destinations</a></li>
     <li><a href="#Message_Selectors">Message Selectors</a></li>
     <li><a href="#Destination_Name_Restrictions">Destination Name Restrictions</a></li>
   </ul></li>
 </ul></div></p>

 <h2 id = "Using_the_STOMP_Protocol">Using the STOMP Protocol</h2>

 <p>Clients can connect to Apollo using the
 <a href="http://stomp.github.com/">STOMP</a> protocol. STOMP provides an interoperable
 messaging wire level protocol that allows any STOMP clients can communicate
 with any STOMP message broker. It aims to provide easy and widespread
 messaging interoperability among many languages, platforms and brokers.</p>

 <p>Apollo supports the following versions of the STOMP specification: </p>

 <ul>
 <li><a href="http://stomp.github.com/stomp-specification-1.0.html">STOMP 1.0</a></li>
 <li><a href="http://stomp.github.com/stomp-specification-1.1.html">STOMP 1.1</a></li>
 <li><a href="http://stomp.github.com/stomp-specification-1.2.html">STOMP 1.2</a></li>
 </ul>

 <p>The specification is short and simple to read, it is highly recommend that users
 to get familiar with it before using one of the many available client libraries.</p>

 <h3 id = "Stomp_Protocol_Options">Stomp Protocol Options</h3>

 <p>You can use the <code>stomp</code> configuration element within the <code>connector</code> element
 in the <code>apollo.xml</code> configuration file to change the default settings used
 in the STOMP protocol implementation.  The <code>stomp</code> element supports the
 following configuration attributes:</p>

 <ul>
 <li><code>buffer_size</code> : How much each producer or subscription will buffer between
 the client and the broker. If not set, it will be auto tuned between <code>640k</code>
 and <code>20k</code> depending on the number of connections open on the broker.</li>
 <li><code>add_user_header</code> :  Name of the header which will be added to every received
 message received.  The value of the header will be set to the id of user that
 sent the message.  Not set by default.</li>
 <li><code>add_timestamp_header</code> :  Name of the header which will be added to every received
 message received.  The value of the header will be set to the time the message
 was received.  The time will be represented as the number of milliseconds elapsed
 since the UNIX epoch in GMT.  Not set by default.</li>
 <li><code>add_redeliveries_header</code> :  Name of the header which will be added to messages
 sent to consumers if the messages has been redelivered.  The value of the header
 will be set to the number of times the message has been redeliverd.  Not set
 by default.</li>
 <li><code>max_header_length</code> : The maximum allowed length of a STOMP header. Defaults
 to <code>10k</code>.</li>
 <li><code>max_headers</code> : The maximum number of allowed headers in a frame.  Defaults
 to 1000.</li>
 <li><code>max_data_length</code> : The maximum size of the body portion of a STOMP frame. <br/>
 Defaults to <code>100M</code>.</li>
 <li><code>die_delay</code> : The amount of time to delay in milliseconds after an <code>ERROR</code>
 message is sent to the client and the socket is closed.</li>
 </ul>

 <p>The stomp configuration element can also be used to control how the destination
 headers are parsed and interpreted.  The supported attributes are:</p>

 <ul>
 <li><code>queue_prefix</code> : Defaults to <code>/queue/</code></li>
 <li><code>topic_prefix</code> : Defaults to <code>/topic/</code></li>
 <li><code>path_separator</code> : Defaults to <code>.</code></li>
 <li><code>destination_separator</code> : Defaults to <code>,</code></li>
 <li><code>any_child_wildcard</code> : Defaults to <code>*</code></li>
 <li><code>regex_wildcard_start</code> : Defaults to <code>{</code></li>
 <li><code>regex_wildcard_end</code> : Defaults to <code>}</code></li>
 <li><code>any_descendant_wildcard</code> : Defaults to <code>**</code></li>
 </ul>

 <p>It also supports nested <code>add_user_header</code> elements to more finely control how
 user headers are added to received STOMP messages.  The <code>add_user_header</code> element
 should contain the name of the header to set on the STOMP message.  It also
 supports the following attributes:</p>

 <ul>
 <li><code>separator</code> : If user has multiple principles which match, this separator
 will be used to delimit them in the header.  If not set, then only the first
 matching principle will be set in the header.</li>
 <li><code>kind</code> : The principle kind to look for.  Defaults to <code>*</code> (matches all
 principle kinds)</li>
 </ul>

 <p>Example:</p>

 <div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code>
 &lt;connector id=&quot;tcp&quot; bind=&quot;tcp://0.0.0.0:61613&quot;&gt;
   &lt;stomp max_header_length=&quot;10000&quot;&gt;
     &lt;add_user_header separator=&quot;,&quot;&gt;user&lt;/add_user_header&gt;
   &lt;/stomp&gt;
 &lt;/connector&gt;
 </code></pre></div>

 <h3 id = "Client_Libraries">Client Libraries</h3>

 <p>There are many open source STOMP clients for different platforms and
 languages.  You can find a full listing of available clients at:</p>

 <ul>
 <li><a href="http://stomp.github.com/implementations.html#Clients"><code>http://stomp.github.com/implementations.html#Clients</code></a></li>
 </ul>

 <p>The Apollo distribution ships with an <code>examples</code> directory
 where you can find some simple examples of how to use some of those
 clients to send and receive messages from a broker instance.</p>

 <p>This section will focus on clarifying the parts of the STOMP specification
 which allow servers to choose their behavior and to describe how to access
 Apollo specific features.</p>

 <h3 id = "Connecting">Connecting</h3>

 <p>The default broker configuration secures access to the broker so that only
 the <code>admin</code> user can connect.  The default password for the <code>admin</code> user
 is <code>password</code>.</p>

 <p>Example STOMP frame to connect to the broker:</p>

 <pre><code>CONNECT

 login:admin
 passcode:password

 ^@</code></pre>

 <p>STOMP 1.0 clients don't specify which virtual host they are connecting to so
 the broker connects those clients to the first virtual host defined in
 it's configuration.  STOMP 1.1 clients must specify a virtual host when they
 connect.  If no configured virtual host <code>host_name</code> matches the client's
 requested host, the connection is terminated with an ERROR.  Therefore,
 it is critical that the virtual hosts configuration define all the
 possible host names that clients may connect to host with.</p>

 <h3 id = "Destination_Types">Destination Types</h3>

 <p>Apollo supports three types of destinations, queues, topics, and
 durable subscriptions.</p>

 <p>The difference between queues and topics is how messages are delivered to
 consumers. A queue will load balance it's messages over the connected
 subscribers so that only one subscriber gets a message. Topics replicate
 every message sent to it to all the connected subscribers.  Queues hold
 on to unconsumed messages even when there are no subscriptions attached,
 while a topic will drop messages when there are no connected subscriptions.</p>

 <p>A durable subscription allows you to create a subscription against a topic
 which will queue messages even after the client disconnects.  Clients
 can reconnect and consume the queued message originating from the topic
 at a later time.</p>

 <p>If you want to send or subscribe to a queue, topic, or durable
 subscription the STOMP destination should be prefixed with <code>/queue/</code>,
 <code>/topic/</code> or <code>/dsub/</code> respectively.</p>

 <p>Example STOMP frame sending to a queue:</p>

 <pre><code>SEND
 destination:/queue/a

 hello queue a
 ^@</code></pre>

 <h3 id = "Topic_Retained_Messages">Topic Retained Messages</h3>

 <p>If a message sent to a Topic has the <code>retain:set</code> header, then
 the message will be 'remembered' by the topic so that if a new
 subscription arrives, the last retained message is sent
 to the subscription.  For example if you want a topic
 to remember the last price published you can send a message
 that looks like:</p>

 <pre><code>SEND
 destination:/topic/stock/IBM
 retain:true

 112.12
 ^@</code></pre>

 <p>You can also send a new message with the <code>retain:remove</code> header
 to have the topic forget about the last retained message.</p>

 <p>Note: retained messages are not retained between broker restarts.</p>

 <h3 id = "Reliable_Messaging">Reliable Messaging</h3>

 <p>Apollo supports reliable messaging by allowing messages to be
 persisted so that they can be recovered if there is failure which kills
 the broker.  Processing persistent messages has orders of magnitude more
 overhead than non-persistent variety.  You should only use it if your
 application really needs it.</p>

 <p>To have a message be persistent, the sender must add the <code>persistent:true</code>
 header to the <code>SEND</code> STOMP frame.  Furthermore, if you are not sending the
 message in a transaction, it is recommend that you also add a <code>receipt</code>
 header.  Once the broker responds with a <code>RECEIPT</code> frame correlated to
 the send, you are guaranteed the broker will not drop the message even if
 a failure occurs.</p>

 <p>Example:</p>

 <pre><code>SEND
 destination:/queue/a
 receipt:001

 hello queue a
 ^@</code></pre>

 <p>The client should not consider the send to have succeeded until he receives
 the correlated <code>RECEIPT</code> frame from the server.  Example:</p>

 <pre><code>RECEIPT
 receipt-id:001

 ^@</code></pre>

 <p>It is important to note that to do reliable messaging, your system will
 be prone to receive duplicate messages.  For example, if your sending
 application dies before it receives the <code>RECEIPT</code> frame, then when it starts
 up again will probably try to send the same message again which may
 cause a duplicate message to get placed on the broker.</p>

 <p>You should only use subscribers which use the <code>client</code> or <code>client-individual</code>
 ack mode to consume reliable messages. Any messages on a queue delivered to a
 client which have not been acked when the client disconnects will get
 redelivered to another subscribed client.</p>

 <h3 id = "Message_Expiration">Message Expiration</h3>

 <p>Apollo supports expiring old messages.  Unconsumed expired messages
 are automatically removed from the queue.  There's two way to specify
 when the message will be expired.  Y</p>

 <p>The first way to configure the expiration is by setting the <code>expires</code> message
 header.  The expiration time must be specified as the number of milliseconds
 since the Unix epoch.</p>

 <p>Example:</p>

 <pre><code>SEND
 destination:/queue/a
 expires:1308690148000

 this message will expire on Tue Jun 21 17:02:28 EDT 2011
 ^@</code></pre>

 <p>The first way to configure the expiration is by setting the <code>ttl</code> message
 header.  The ttl will be intereted to mean the number of milliseconds from
 when the server receives the message.  The broker will add an <code>expires</code>
 header to the message on your behalf.</p>

 <p>Example:</p>

 <pre><code>SEND
 destination:/queue/a
 ttl:2000

 This message will expire in 2 seconds.
 ^@</code></pre>

 <h3 id = "Subscription_Flow_Control">Subscription Flow Control</h3>

 <p>You can add a <code>credit</code> header to the <code>SUBSCRIBE</code> frame to control the
 flow of messages delivered to the client. Each subscription maintains 2
 credit windows which allows you to control the flow of messages either based
 on number of messages sent or total number of content bytes delivered to the
 client. The content bytes are the body of the frame which is usually also
 set on the <code>content-length</code> header. If either of the two credit windows have
 a positive value, the server will deliver messages to the client.</p>

 <p>The <code>credit</code> header value is expected to use the
 <code>count[,size]</code> syntax where:</p>

 <ul>
 <li>count: initial setting of the credit window tracking the remaining number
 of messages that can be sent.  Must be specified.</li>
 <li>size: initial setting of the credit window tracking the remaining number
 of content bytes that can be sent.  Defaults to the receive buffer size of
 the TCP socket which is typically 65536 bytes.</li>
 </ul>

 <p>If the <code>credit</code> header is not specified it has the same effect
 as if it had been set to <code>credit:655360,655360</code>.  This setting allows the broker
 to optimally stream many small messages to the client or without overloading
 the clients processing buffers.</p>

 <p>As messages are sent from the server to the client, the credit windows are
 reduced by the corresponding amount. When the client send <code>ACK</code> frames to the
 server, the credit windows are incremented by the number of messages and content
 sizes corresponding to the messages that were acknowledged.</p>

 <p>Example:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 destination:/queue/foo
 credit:5,0

 ^@</code></pre>

 <p>The above example would cause the subscription to only receive at most 5
 messages if the client is not sending any <code>ACK</code> messages back to the server.</p>

 <p>If you need to receive more messages without acknowledging them than the
 size of the credit window, you should use transactions and transactionally
 <code>ACK</code> messages as they are received.  A transactional ACK increases the
 credit window without actually consuming the messages.  If the transaction
 is aborted subsequent acknowledgements of a previously acknowledged message
 does not increase the credit window.</p>

 <!-- The following feature seems complicated and not really that useful.-->

 <!-- Commenting out as it may get removed. -->

 <!--

 If the `auto` option is set to `false`, then the credit windows are only
 increased when the server receives `ACK` frames which contain a `credit`
 header. The header value is expected to use the `count[,size]` syntax. If
 `size` is specified, it defaults to 0.

 Example:

     SUBSCRIBE
     id:mysub
     destination:/queue/foo
     credit:1,0,false

     ^@
     ACK
     id:mysub
     message-id:id-52321
     credit:1,1204

     ^@

 You can also use the `ACK` frame to increase the credit windows sizes
 without needing to acknowledge as message. To do this, don't include the
 `message-id` header in the `ACK` frame. Example:

     ACK
     id:mysub
     credit:3

     ^@
 -->

 <h3 id = "Topic_Durable_Subscriptions">Topic Durable Subscriptions</h3>

 <p>A durable subscription is a queue which is subscribed to a topic so that even
 if the client which created the durable subscription is not online, he can
 still get a copy of all the messages sent to the topic when he comes back
 online. Multiple clients can subscribe to the same durable subscription and
 since it's backed by a queue, those subscribers will have the topic's messages
 load balanced across them.</p>

 <p>To create or reattach to a a durable subscription with STOMP, you uniquely
 name the durable subscription using the <code>id</code> header on the <code>SUBSCRIBE</code> frame
 and also adding a <code>persistent:true</code> header. Example:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 persistent:true
 destination:/topic/foo

 ^@</code></pre>

 <p>A standard <code>UNSUBSCRIBE</code> frame does not destroy the durable subscription, it
 only disconnects the client from the durable subscription. To destroy a
 durable subscription, you must once again add <code>persistent:true</code> header to the
 <code>UNSUBSCRIBE</code> frame. Example:</p>

 <pre><code>UNSUBSCRIBE
 id:mysub
 persistent:true

 ^@</code></pre>

 <p>If the durable subscription already exists you can address it directly using
 <code>/dsub/</code> prefix on the <code>destination</code> header. For example, send a message to
 the previously created <code>mysub</code> durable subscription, you send the following
 STOMP frame:</p>

 <pre><code>SEND
 destination:/dsub/mysub

 hello durable sub!
 ^@</code></pre>

 <p>Similarly, you can also subscribe to the subscription in the same way:</p>

 <pre><code>SUBSCRIBE
 id:0
 destination:/dsub/mysub

 ^@</code></pre>

 <p>Unlike typical STOMP subscriptions id's which are local to the STOMP client's
 connection, the durable subscription id's are global across a virtual host. If
 two different connections use the same durable subscription id, then messages
 from the subscription will get load balanced across the two connections. If
 the second connection uses a different <code>destination</code> or <code>selector</code> header,
 then updates the original subscription, and the original connection will
 subsequently only receive messages matching the updated destination or
 selector.</p>

 <h3 id = "Browsing_Subscriptions">Browsing Subscriptions</h3>

 <p>A normal subscription on a queue will consume messages so that no other
 subscription will get a copy of the message. If you want to browse all the
 messages on a queue in a non-destructive fashion, you can create browsing
 subscription. Browsing subscriptions also works with durable subscriptions
 since they are backed by a queue. To make a a browsing subscription, just add
 the <code>browser:true</code> header to the <code>SUBSCRIBE</code> frame. For example:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 browser:true
 destination:/queue/foo

 ^@</code></pre>

 <p>Once the broker sends a browsing subscription the last message in the queue,
 it will send the subscription a special &ldquo;end of browse&rdquo; message to indicate
 browsing has completed and that the subscription should not expect any more
 messages. The &ldquo;end of browse&rdquo; message will have a <code>browser:end</code> header set.
 Example:</p>

 <pre><code>MESSAGE
 subscription:mysub
 destination:
 message-id:
 browser:end

 ^@</code></pre>

 <p>If you want the browsing subscription to remain active and continue to listen
 for message once the last message on the queue is reached, you should add the
 <code>browser-end:false</code> header to the <code>SUBSCRIBE</code> frame. When the
 <code>browser-end:false</code> header is added the subscription will not be sent the &ldquo;end
 of browse&rdquo; message previously described.</p>

 <h3 id = "Queue_Message_Sequences">Queue Message Sequences</h3>

 <p>As messages are added to a queue in a broker, they are assigned an
 incrementing sequence number. Messages delivered to subscribers can be updated
 to include the sequence number if the <code>include-seq</code> header is added to the
 <code>SUBSCRIBE</code> frame. This header should be set to a header name which will be
 added messages delivered to hold value of the sequence number.</p>

 <p>Example:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 destination:/queue/foo
 include-seq:seq

 ^@</code></pre>

 <p>Then you can expect to receive messages like:</p>

 <pre><code>MESSAGE
 subscription:mysub
 destination:/queue/foo
 seq:1

 Hello
 ^@
 MESSAGE
 subscription:mysub
 destination:/queue/foo
 seq:2

 World
 ^@</code></pre>

 <p>Furthermore, you can configure the <code>SUBSCRIBE</code> frame so that the subscription
 only receives messages that have a sequence id that is equal to or greater
 than a requested value by using the <code>from-seq</code> header. Example:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 destination:/queue/foo
 from-seq:10

 ^@</code></pre>

 <p>If the <code>from-seq</code> is set to <code>-1</code>, then the subscription will receive messages
 from the tail of the queue. In other words, it will only receive new messages
 sent to the queue.</p>

 <p>Note: You can only use the <code>from-seq</code> header with normal destinations. If you
 attempt to use it with a wildcard or composite destination then the connection
 will be closed due to invalid usage.</p>

 <h3 id = "Using_Queue_Browsers_to_Implement_Durable_Topic_Subscriptions">Using Queue Browsers to Implement Durable Topic Subscriptions</h3>

 <p>You can use queue browsers with consumer side message sequence tracking to
 achieve the same semantics as durable topics subscriptions but with a better
 performance profile. Since browsers do not delete messages from a queue, when
 you use multiple browsers against one queue you get the same broadcast effects
 that a topic provides.</p>

 <p>In this approach the subscribing application keeps track of the last sequence
 number processed from the subscription. The sequence number is typically
 stored as part of the unit of work which is processing the message. The
 subscription can use the default auto acknowledge mode but still get 'once and
 only once' delivery guarantees since:</p>

 <ul>
 <li>consuming application records the last message sequence that
 was processed</li>
 <li>message are not deleted when delivered to the subscriber</li>
 <li>on restart consuming application continues receiving from the queue
 for the last sequence that it received.</li>
 </ul>

 <p>The <code>SUBSCRIBE</code> frame used to create the browser should add the <code>include-seq</code>,
 <code>from-seq</code>, and <code>browser-end</code> headers so that they can resume receiving
 messages from the queue from the last known sequence. If you are starting a
 new consumer that does not have a last processed sequence number, you can
 either set <code>from-seq</code> to:</p>

 <ul>
 <li><code>0</code> to start receiving at the head of the queue which sends
 the subscription a copy of all the messages that are currently
 queued.</li>
 <li><code>-1</code> to start receiving at the tail of the queue which to skips
 over all the message that exist in the queue so that the subscription
 only receives new messages.</li>
 </ul>

 <p>Example:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 destination:/queue/foo
 browser:true
 browser-end:false
 include-seq:seq
 from-seq:0

 ^@</code></pre>

 <p>Since this approach does not consume the messages from the queue, you should
 either:</p>

 <ul>
 <li>Send messages to the queue with an expiration time so that they are
 automatically delete once the expiration time is reached.</li>
 <li>Periodically run a normal consumer application which can cursor the queue
 and delete messages are are deemed no longer needed.</li>
 </ul>

 <h3 id = "Exclusive_Subscriptions">Exclusive Subscriptions</h3>

 <p>We maintain the order of messages in queues and dispatch them to
 subscriptions in order. However if you have multiple subscriptions consuming
 from the same queue, you will loose the guarantee of processing the messages
 in order; since the messages may be processed concurrently on different
 subscribers.</p>

 <p>Sometimes it is important to guarantee the order in which messages are
 processed. e.g. you don't want to process the update to an order until an
 insert has been done; or to go backwards in time, overwriting an newer update
 of an order with an older one etc.</p>

 <p>So what folks have to do in clusters is often to only run one consumer
 process in a cluster to avoid loosing the ordering. The problem with this is
 that if that process goes down, no one is processing the queue any more,
 which can be problem.</p>

 <p>Apollo supports exclusive subscriptions which avoids the end user
 having to restrict himself to only running one process. The broker will pick
 a single subscription to get all the messages for a queue to ensure ordering.
 If that subscription fails, the broker will auto failover and choose another
 subscription.</p>

 <p>An exclusive subscription is created by adding a <code>exclusive:true</code> header
 to the <code>SUBSCRIBE</code> frame.  Example:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 exclusive:true
 destination:/queue/foo

 ^@</code></pre>

 <h3 id = "Message_Groups">Message Groups</h3>

 <p>Message Groups are an enhancement to the Exclusive Consumer feature to provide</p>

 <ul>
 <li>guaranteed ordering of the processing of related messages across a single queue</li>
 <li>load balancing of the processing of messages across multiple consumers</li>
 <li>high availability / auto-failover to other consumers if a JVM goes down</li>
 </ul>

 <p>Message Groups are logically like a parallel Exclusive Consumer. Rather
 than all messages going to a single consumer, the stomp <code>message_group</code> header
 is used to define which message group the message belongs to. The Message Group
 feature then ensures that all messages for the same message group will be sent to
 the currently assigned consumer for the group.  The assigned consumer consumer
 for a message group may change but not before all messages sent to the previous
 consumer are acked or if the consumer is disconnected.</p>

 <p>Another way of explaining Message Groups is that it provides sticky load balancing
 of messages across consumers; where the message group value is kinda like a HTTP
 session ID or cookie value and the message broker is acting like a HTTP load balancer.</p>

 <p>Here is an example message with the message group set:</p>

 <pre><code>MESSAGE
 destination:/queue/PO.REQUEST
 message_group:hiram

 PO145
 ^@</code></pre>

 <p>The broker uses consistent hashing to map message groups to consumers.  When you add another
 subscription to a queue, the broker will first wait for messages sent to previous subscriptions
 to be processed and then the broker rebalances the message groups across the attached consumers.</p>

 <h3 id = "Temporary_Destinations">Temporary Destinations</h3>

 <p>Temporary destinations are typically used to receive response messages in
 a request/response messaging exchange.  A temporary destination can only
 be consumed by a subscription created on the connection which is associated
 with the temporary destination.  Once the connection is closed, all associated
 temporary destinations are removed. Temporary destinations are prefixed with:</p>

 <ul>
 <li><code>/temp-queue/</code> - For temporary queues.  Has the same delivery semantics as queues.</li>
 <li><code>/temp-topic/</code> - For temporary topics.  It has the same delivery semantics of topics.</li>
 </ul>

 <p>In a request/response scenario, you would first subscribe to the temporary topic:</p>

 <pre><code>SUBSCRIBE
 id:mysub
 destination:/temp-queue/example

 ^@</code></pre>

 <p>Then you would send a request with the reply-to header set to the temporary destination.
 Example:</p>

 <pre><code>SEND
 destination:/queue/PO.REQUEST
 reply-to:/temp-queue/example

 PO145
 ^@</code></pre>

 <p>The consumer receiving the request will receive a message similar to:</p>

 <pre><code>MESSAGE
 subscription:foo
 reply-to:/queue/temp.default.23.example
 destination:/queue/PO.REQUEST
 reply-to:/temp-queue/example

 PO145</code></pre>

 <p>Notice that the reply-to` header value is updated from a temporary destination
 name to normal destination name.  The subscription servicing he requests should respond
 to the updated destination value (<code>/queue/temp.default.23.example</code> in the example above).</p>

 <p>Temporary destination names actually map to normal queues and topics. They just have
 a <code>temp.&lt;broker&#95;id&gt;.&lt;connection&#95;id&gt;.</code> prefix.  Any destination which starts with
 <code>temp.</code> has a security policy which only allows the connection which created it
 to subscribe from it.  These destinations are also auto deleted once the connection
 is closed.</p>

 <h3 id = "Destination_Wildcards">Destination Wildcards</h3>

 <p>We support destination wildcards to easily subscribe to multiple destinations
 with one subscription. This concept has been popular in financial market data
 for some time as a way of organizing events (such as price changes) into
 hierarchies and to use wildcards for easy subscription of the range of
 information you're interested in.</p>

 <ul>
 <li><code>.</code> is used to separate names in a path</li>
 <li><code>*</code> is used to match any name in a path</li>
 <li><code>{regex}</code> is used to match a path name against a regular expression.</li>
 <li><code>**</code> is used to recursively match path names</li>
 </ul>

 <p>For example imagine you are sending price messages from a stock exchange feed.
 You might use some kind of destination naming conventions such as:</p>

 <ul>
 <li><code>/topic/PRICE.STOCK.NASDAQ.IBM</code> to publish IBM's price on NASDAQ and</li>
 <li><code>/topic/PRICE.STOCK.NYSE.SUNW</code> to publish Sun's price on the New York Stock Exchange</li>
 </ul>

 <p>A subscriber could then use exact destinations to subscribe to exactly the
 prices it requires. Or it could use wildcards to define hierarchical pattern
 matches to the destinations to subscribe from.</p>

 <p>For example using the example above, these subscriptions are possible</p>

 <ul>
 <li><code>/topic/PRICE.**</code> : Any price for any product on any exchange</li>
 <li><code>/topic/PRICE.STOCK.**</code> : Any price for a stock on any exchange</li>
 <li><code>/topic/PRICE.STOCK.NASDAQ.*</code> : Any stock price on NASDAQ</li>
 <li><code>/topic/PRICE.STOCK.*.IBM</code> : Any IBM stock price on any exchange</li>
 <li><code>/topic/PRICE.STOCK.*.I*</code> : Any stock price starting with 'I' on any exchange</li>
 <li><code>/topic/PRICE.STOCK.*.*{[0-9]}</code> : Any stock price that ends in a digit on any exchange</li>
 </ul>

 <p>Destination wildcards can only be used in a SUBSCRIBE frame.</p>

 <h3 id = "Composite_Destinations">Composite Destinations</h3>

 <p>You can use composite destinations to send or subscribe to multiple
 destinations at one time. You use separator of <code>,</code> between destination
 names.  For example, to send one message to 2 queues and 1 topic:</p>

 <pre><code>SEND
 destination:/queue/a,/queue/b,/topic/c

 Composites rock!
 ^@</code></pre>

 <h3 id = "Message_Selectors">Message Selectors</h3>

 <p>Message selectors allow a subscription to only receive a subset of the
 messages sent to a destination.  The selector acts like a filter which
 is applied against the message properties and only those messages
 which match pass through to the subscription.  </p>

 <p>Selectors are defined using SQL 92 syntax and typically apply to message
 headers; whether the standard properties available on a JMS message or custom
 headers you can add via the JMS code.</p>

 <p>Here is an example:</p>

 <pre><code>type = 'car' AND color = 'blue' AND weight &gt; 2500</code></pre>

 <p>To create a subscription with a message selector, you set the <code>selector</code>
 header in the STOMP <code>SUBSCRIBE</code> frame to the desired selector. Example:</p>

 <pre><code>SUBSCRIBE
 id:sub0
 selector:type = 'car' AND color = 'blue' AND weight &gt; 2500
 destination:/topic/foo

 ^@</code></pre>

 <h3 id = "Destination_Name_Restrictions">Destination Name Restrictions</h3>

 <p>Destination names are restricted to using the characters <code>a-z</code>, <code>A-Z</code>, <code>0-9</code>,
 <code>_</code>, <code>-</code> <code>%</code>, <code>~</code>, <code>:</code>, ' ', '(', ')' or <code>.</code> in addition to composite separator <code>,</code> and the wild
 card <code>*</code>.  Any other characters must be UTF-8 and then URL encoded if you wish to
 preserve their significance.</p>
         <div></div>
       </div>
     </div>
   </body>
 </html>