activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chir...@apache.org
Subject svn commit: r1390773 - in /activemq/activemq-apollo/trunk/apollo-website/src: documentation/index.page documentation/openwire-features.md documentation/openwire-manual.md documentation/stomp-manual.md documentation/user-manual.md index.page
Date Wed, 26 Sep 2012 23:12:27 GMT
Author: chirino
Date: Wed Sep 26 23:12:26 2012
New Revision: 1390773

URL: http://svn.apache.org/viewvc?rev=1390773&view=rev
Log:
Refactored out the STOMP documentation into it's own manual.  Improved front page documentation and links to the different protocol specific manuals.

Added:
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-manual.md
      - copied, changed from r1390772, activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-features.md
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/stomp-manual.md
Removed:
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-features.md
Modified:
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md
    activemq/activemq-apollo/trunk/apollo-website/src/index.page

Modified: activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page?rev=1390773&r1=1390772&r2=1390773&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page Wed Sep 26 23:12:26 2012
@@ -25,6 +25,8 @@ ${project_slogan}
 
 * [Getting Started Guide](getting-started.html)
 * [User Manual](user-manual.html)
+* [STOMP Protocol Manual](stomp-manual.html)
+* [OpenWire Protocol Manual](openwire-manual.html) 
 * [Migration Guide](migration-guide.html)
 * [Management API](management-api.html)
 * [Contributor Documentation](../community/developers.html)

Copied: activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-manual.md (from r1390772, activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-features.md)
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-manual.md?p2=activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-manual.md&p1=activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-features.md&r1=1390772&r2=1390773&rev=1390773&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-features.md (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/openwire-manual.md Wed Sep 26 23:12:26 2012
@@ -1,8 +1,8 @@
-## Using the OpenWire Protocol
+# Apollo ${project_version} OpenWire Protocol Manual
 
 {:toc:2-5}
 
-### OpenWire
+## Using the OpenWire Protocol
 
 Clients can connect to ${project_name} using the
 [OpenWire](http://activemq.apache.org/openwire.html) protocol. OpenWire is a binary,
@@ -270,15 +270,23 @@ to the broker or to to virtual host, the
 * Persistent Messaging
 * Message Expiration
 
-### OpenWire implementation features to come in the near future:
+### Unsupported OpenWire features:
 
+You will get bad/undefined behaviour if you try to use any of the following OpenWire features:
+
+* XA transactions
 * [Message Groups using JMSXGroupID](http://activemq.apache.org/message-groups.html)
 * [Subscription recovery/retroactive consumer](http://activemq.apache.org/retroactive-consumer.html)
+* [Exclusive Consumer with Priority](http://activemq.apache.org/exclusive-consumer.html)
+* [Virtual Destinations](http://activemq.apache.org/virtual-destinations.html)
+
+You can use Durable Subscriptions and/or [Mirrored Queues](user-manual.html#Mirrored_Queues) to get
+the same/similar behaviour that [Virtual Destinations](http://activemq.apache.org/virtual-destinations.html) provide.
+
+<!-- The following are not really OpenWire features.. but just general brokers features.
 * [Network of brokers](http://activemq.apache.org/networks-of-brokers.html)
 * [Shared-state Master/Slave](http://activemq.apache.org/shared-file-system-master-slave.html)
-* [XA transaction]()
-* [Exclusive Consumer with Priority](http://activemq.apache.org/exclusive-consumer.html)
 * [Startup Destinations](http://activemq.apache.org/configure-startup-destinations.html)
 * [Delete inactive dests](http://activemq.apache.org/delete-inactive-destinations.html)
-* [Virtual Dests](http://activemq.apache.org/virtual-destinations.html)
 * [JMX](http://activemq.apache.org/jmx.html)
+-->
\ No newline at end of file

Added: activemq/activemq-apollo/trunk/apollo-website/src/documentation/stomp-manual.md
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/stomp-manual.md?rev=1390773&view=auto
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/stomp-manual.md (added)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/stomp-manual.md Wed Sep 26 23:12:26 2012
@@ -0,0 +1,677 @@
+# Apollo ${project_version} STOMP Protocol Manual
+
+{:toc:2-5}
+
+## Using the STOMP Protocol
+
+Clients can connect to ${project_name} using the
+[STOMP](http://stomp.github.com/) 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.
+
+${project_name} supports the following versions of the STOMP specification: 
+
+* [STOMP 1.0](http://stomp.github.com/stomp-specification-1.0.html)
+* [STOMP 1.1](http://stomp.github.com/stomp-specification-1.1.html)
+
+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.
+
+### Stomp Protocol Options
+
+You can use the `stomp` configuration element within the `connector` element
+in the `apollo.xml` configuration file to change the default settings used
+in the STOMP protocol implementation.  The `stomp` element supports the 
+following configuration attributes:
+
+* `buffer_size` : How much each producer or subscription will buffer between
+   the client and the broker. If not set, it will be auto tuned between `640k`
+   and `20k` depending on the number of connections open on the broker.
+* `add_user_header` :  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.
+* `add_timestamp_header` :  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.
+* `add_redeliveries_header` :  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.
+* `max_header_length` : The maximum allowed length of a STOMP header. Defaults 
+  to `10k`.
+* `max_headers` : The maximum number of allowed headers in a frame.  Defaults 
+  to 1000.
+* `max_data_length` : The maximum size of the body portion of a STOMP frame.  
+  Defaults to `100M`.
+* `die_delay` : The amount of time to delay in milliseconds after an `ERROR` 
+  message is sent to the client and the socket is closed.
+
+The stomp configuration element can also be used to control how the destination 
+headers are parsed and interpreted.  The supported attributes are:
+  
+* `queue_prefix` : Defaults to `/queue/`
+* `topic_prefix` : Defaults to `/topic/`
+* `path_separator` : Defaults to `.`
+* `destination_separator` : Defaults to `,`
+* `any_child_wildcard` : Defaults to `*`
+* `regex_wildcard_start` : Defaults to `{`
+* `regex_wildcard_end` : Defaults to `}`
+* `any_descendant_wildcard` : Defaults to `**`
+
+It also supports nested `add_user_header` elements to more finely control how
+user headers are added to received STOMP messages.  The `add_user_header` element
+should contain the name of the header to set on the STOMP message.  It also 
+supports the following attributes:
+
+* `separator` : 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.
+* `kind` : The principle kind to look for.  Defaults to `*` (matches all 
+  principle kinds)
+
+Example:
+
+{pygmentize:: xml}
+<connector id="tcp" bind="tcp://0.0.0.0:61613">
+  <stomp max_header_length="10000">
+    <add_user_header separator=",">user</add_user_header>
+  </stomp>
+</connector>
+{pygmentize}
+
+
+### Client Libraries
+
+There are many open source STOMP clients for different platforms and
+languages.  You can find a full listing of available clients at:
+
+* [`http://stomp.github.com/implementations.html#Clients`](http://stomp.github.com/implementations.html#Clients)
+
+The ${project_name} distribution ships with an `examples` 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.
+
+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
+${project_name} specific features.
+
+### Connecting
+
+The default broker configuration secures access to the broker so that only
+the `admin` user can connect.  The default password for the `admin` user 
+is `password`.
+
+Example STOMP frame to connect to the broker:
+
+    CONNECT
+    
+    login:admin
+    passcode:password
+    
+    ^@
+
+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 `host_name` 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.
+
+### Destination Types
+
+${project_name} supports three types of destinations, queues, topics, and
+durable subscriptions.
+
+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.
+
+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.
+
+If you want to send or subscribe to a queue, topic, or durable
+subscription the STOMP destination should be prefixed with `/queue/`,
+`/topic/` or `/dsub/` respectively.
+
+Example STOMP frame sending to a queue:
+
+    SEND
+    destination:/queue/a
+
+    hello queue a
+    ^@
+
+### Topic Retained Messages
+
+If a message sent to a Topic has the `retain:set` 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:
+
+    SEND
+    destination:/topic/stock/IBM
+    retain:true
+
+    112.12
+    ^@
+
+You can also send a new message with the `retain:remove` header
+to have the topic forget about the last retained message.
+
+Note: retained messages are not retained between broker restarts.
+
+### Reliable Messaging
+
+${project_name} 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.
+
+To have a message be persistent, the sender must add the `persistent:true`
+header to the `SEND` STOMP frame.  Furthermore, if you are not sending the 
+message in a transaction, it is recommend that you also add a `receipt`
+header.  Once the broker responds with a `RECEIPT` frame correlated to 
+the send, you are guaranteed the broker will not drop the message even if
+a failure occurs.
+
+Example:
+
+    SEND
+    destination:/queue/a
+    receipt:001
+
+    hello queue a
+    ^@
+
+The client should not consider the send to have succeeded until he receives
+the correlated `RECEIPT` frame from the server.  Example:
+
+    RECEIPT
+    receipt-id:001
+    
+    ^@
+
+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 `RECEIPT` 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.
+
+You should only use subscribers which use the `client` or `client-individual`
+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.
+
+### Message Expiration
+
+${project_name} supports expiring old messages.  Unconsumed expired messages 
+are automatically removed from the queue.  You just need to specify when
+the message expires by setting the `expires` message header.  The expiration
+time must be specified as the number of milliseconds since the Unix epoch.
+
+Example:
+
+    SEND
+    destination:/queue/a
+    expires:1308690148000
+
+    this message will expire on Tue Jun 21 17:02:28 EDT 2011
+    ^@
+
+### Subscription Flow Control
+
+You can add a `credit` header to the `SUBSCRIBE` 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 `content-length` header. If either of the two credit windows have
+a positive value, the server will deliver messages to the client.
+
+The `credit` header value is expected to use the
+`count[,size]` syntax where:
+
+ * count: initial setting of the credit window tracking the remaining number 
+   of messages that can be sent.  Must be specified.
+ * 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.
+
+If the `credit` header is not specified it has the same effect
+as if it had been set to `credit:655360,655360`.  This setting allows the broker
+to optimally stream many small messages to the client or without overloading
+the clients processing buffers.
+
+As messages are sent from the server to the client, the credit windows are
+reduced by the corresponding amount. When the client send `ACK` frames to the 
+server, the credit windows are incremented by the number of messages and content 
+sizes corresponding to the messages that were acknowledged.
+
+Example:
+
+    SUBSCRIBE
+    id:mysub
+    destination:/queue/foo
+    credit:5,0
+    
+    ^@
+
+The above example would cause the subscription to only receive at most 5
+messages if the client is not sending any `ACK` messages back to the server.
+
+If you need to receive more messages without acknowledging them than the
+size of the credit window, you should use transactions and transactionally
+`ACK` 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.
+
+<!-- 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
+    
+    ^@
+-->
+
+### Topic Durable Subscriptions
+
+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.
+
+To create or reattach to a a durable subscription with STOMP, you uniquely
+name the durable subscription using the `id` header on the `SUBSCRIBE` frame
+and also adding a `persistent:true` header. Example:
+
+    SUBSCRIBE
+    id:mysub
+    persistent:true
+    destination:/topic/foo
+    
+    ^@
+
+A standard `UNSUBSCRIBE` 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 `persistent:true` header to the
+`UNSUBSCRIBE` frame. Example:
+
+    UNSUBSCRIBE
+    id:mysub
+    persistent:true
+    
+    ^@
+
+If the durable subscription already exists you can address it directly using
+`/dsub/` prefix on the `destination` header. For example, send a message to
+the previously created `mysub` durable subscription, you send the following
+STOMP frame:
+
+
+    SEND
+    destination:/dsub/mysub
+
+    hello durable sub!
+    ^@
+
+Similarly, you can also subscribe to the subscription in the same way:
+
+    SUBSCRIBE
+    id:0
+    destination:/dsub/mysub
+    
+    ^@
+
+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 `destination` or `selector` header,
+then updates the original subscription, and the original connection will
+subsequently only receive messages matching the updated destination or
+selector.
+
+### Browsing Subscriptions
+
+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 `browser:true` header to the `SUBSCRIBE` frame. For example:
+
+    SUBSCRIBE
+    id:mysub
+    browser:true
+    destination:/queue/foo
+    
+    ^@
+
+Once the broker sends a browsing subscription the last message in the queue,
+it will send the subscription a special "end of browse" message to indicate
+browsing has completed and that the subscription should not expect any more
+messages. The "end of browse" message will have a `browser:end` header set.
+Example:
+
+    MESSAGE
+    subscription:mysub
+    destination:
+    message-id:
+    browser:end
+    
+    ^@
+
+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
+`browser-end:false` header to the `SUBSCRIBE` frame. When the
+`browser-end:false` header is added the subscription will not be sent the "end
+of browse" message previously described.
+
+### Queue Message Sequences
+
+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 `include-seq` header is added to the
+`SUBSCRIBE` frame. This header should be set to a header name which will be
+added messages delivered to hold value of the sequence number.
+
+Example:
+
+    SUBSCRIBE
+    id:mysub
+    destination:/queue/foo
+    include-seq:seq
+    
+    ^@
+
+Then you can expect to receive messages like:
+
+    MESSAGE
+    subscription:mysub
+    destination:/queue/foo
+    seq:1
+    
+    Hello
+    ^@
+    MESSAGE
+    subscription:mysub
+    destination:/queue/foo
+    seq:2
+    
+    World
+    ^@
+
+Furthermore, you can configure the `SUBSCRIBE` 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 `from-seq` header. Example:
+
+    SUBSCRIBE
+    id:mysub
+    destination:/queue/foo
+    from-seq:10
+    
+    ^@
+
+If the `from-seq` is set to `-1`, 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.
+
+Note: You can only use the `from-seq` 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.
+
+### Using Queue Browsers to Implement Durable Topic Subscriptions
+
+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.
+
+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:
+
+ * consuming application records the last message sequence that 
+   was processed
+ * message are not deleted when delivered to the subscriber
+ * on restart consuming application continues receiving from the queue
+   for the last sequence that it received.
+
+The `SUBSCRIBE` frame used to create the browser should add the `include-seq`,
+`from-seq`, and `browser-end` 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 `from-seq` to:
+
+ * `0` to start receiving at the head of the queue which sends
+   the subscription a copy of all the messages that are currently 
+   queued. 
+ * `-1` 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.
+
+Example:
+
+    SUBSCRIBE
+    id:mysub
+    destination:/queue/foo
+    browser:true
+    browser-end:false
+    include-seq:seq
+    from-seq:0
+    
+    ^@
+
+Since this approach does not consume the messages from the queue, you should
+either:
+
+* Send messages to the queue with an expiration time so that they are 
+  automatically delete once the expiration time is reached.
+* Periodically run a normal consumer application which can cursor the queue
+  and delete messages are are deemed no longer needed.
+
+### Exclusive Subscriptions
+
+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.
+
+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.
+
+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.
+
+${project_name} 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.
+
+An exclusive subscription is created by adding a `exclusive:true` header
+to the `SUBSCRIBE` frame.  Example:
+
+    SUBSCRIBE
+    id:mysub
+    exclusive:true
+    destination:/queue/foo
+    
+    ^@
+
+### Temporary Destinations
+
+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:
+
+* `/temp-queue/` - For temporary queues.  Has the same delivery semantics as queues.
+* `/temp-topic/` - For temporary topics.  It has the same delivery semantics of topics.
+
+In a request/response scenario, you would first subscribe to the temporary topic:
+
+    SUBSCRIBE
+    id:mysub
+    destination:/temp-queue/example
+    
+    ^@
+
+Then you would send a request with the reply-to header set to the temporary destination. 
+Example:
+
+    SEND
+    destination:/queue/PO.REQUEST
+    reply-to:/temp-queue/example
+
+    PO145
+    ^@
+
+The consumer receiving the request will receive a message similar to:
+
+    MESSAGE
+    subscription:foo
+    reply-to:/queue/temp.default.23.example
+    destination:/queue/PO.REQUEST
+    reply-to:/temp-queue/example
+    
+    PO145
+
+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 (`/queue/temp.default.23.example` in the example above).
+
+Temporary destination names actually map to normal queues and topics. They just have
+a `temp.<broker_id>.<connection_id>.` prefix.  Any destination which starts with
+`temp.` 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.
+
+### Destination Wildcards
+
+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.
+
+* `.` is used to separate names in a path
+* `*` is used to match any name in a path
+* `{regex}` is used to match a path name against a regular expression.
+* `**` is used to recursively match path names
+
+For example imagine you are sending price messages from a stock exchange feed.
+You might use some kind of destination naming conventions such as:
+
+* `/topic/PRICE.STOCK.NASDAQ.IBM` to publish IBM's price on NASDAQ and
+* `/topic/PRICE.STOCK.NYSE.SUNW` to publish Sun's price on the New York Stock Exchange
+
+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.
+
+For example using the example above, these subscriptions are possible
+
+* `/topic/PRICE.**` : Any price for any product on any exchange
+* `/topic/PRICE.STOCK.**` : Any price for a stock on any exchange
+* `/topic/PRICE.STOCK.NASDAQ.*` : Any stock price on NASDAQ
+* `/topic/PRICE.STOCK.*.IBM` : Any IBM stock price on any exchange
+* `/topic/PRICE.STOCK.*.I*` : Any stock price starting with 'I' on any exchange
+* `/topic/PRICE.STOCK.*.*{[0-9]}` : Any stock price that ends in a digit on any exchange
+
+Destination wildcards can only be used in a SUBSCRIBE frame.
+
+### Composite Destinations
+
+You can use composite destinations to send or subscribe to multiple
+destinations at one time. You use separator of `,` between destination
+names.  For example, to send one message to 2 queues and 1 topic:
+
+    SEND
+    destination:/queue/a,/queue/b,/topic/c
+
+    Composites rock!
+    ^@
+
+### Message Selectors
+
+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.  
+
+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.
+
+Here is an example:
+
+    type = 'car' AND color = 'blue' AND weight > 2500
+
+To create a subscription with a message selector, you set the `selector`
+header in the STOMP `SUBSCRIBE` frame to the desired selector. Example:
+
+    SUBSCRIBE
+    id:sub0
+    selector:type = 'car' AND color = 'blue' AND weight > 2500
+    destination:/topic/foo
+    
+    ^@
+
+### Destination Name Restrictions
+
+Destination names are restricted to using the characters `a-z`, `A-Z`, `0-9`,
+`_`, `-` `%`, `~`, `:`, ' ', or `.` in addition to composite separator `,` and the wild
+card `*`.  Any other characters must be UTF-8 and then URL encoded if you wish to 
+preserve their significance.
+

Modified: activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md?rev=1390773&r1=1390772&r2=1390773&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md Wed Sep 26 23:12:26 2012
@@ -1164,676 +1164,7 @@ Just like in the case of the `store-expo
 `mybroker`'s configuration and import the archive into the first virtual
 host's message store.
 
-## Using the STOMP Protocol
-
-Clients can connect to ${project_name} using the
-[STOMP](http://stomp.github.com/) 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.
-
-${project_name} supports the following versions of the STOMP specification: 
-
-* [STOMP 1.0](http://stomp.github.com/stomp-specification-1.0.html)
-* [STOMP 1.1](http://stomp.github.com/stomp-specification-1.1.html)
-
-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.
-
-### Stomp Protocol Options
-
-You can use the `stomp` configuration element within the `connector` element
-in the `apollo.xml` configuration file to change the default settings used
-in the STOMP protocol implementation.  The `stomp` element supports the 
-following configuration attributes:
-
-* `buffer_size` : How much each producer or subscription will buffer between
-   the client and the broker. If not set, it will be auto tuned between `640k`
-   and `20k` depending on the number of connections open on the broker.
-* `add_user_header` :  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.
-* `add_timestamp_header` :  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.
-* `add_redeliveries_header` :  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.
-* `max_header_length` : The maximum allowed length of a STOMP header. Defaults 
-  to `10k`.
-* `max_headers` : The maximum number of allowed headers in a frame.  Defaults 
-  to 1000.
-* `max_data_length` : The maximum size of the body portion of a STOMP frame.  
-  Defaults to `100M`.
-* `die_delay` : The amount of time to delay in milliseconds after an `ERROR` 
-  message is sent to the client and the socket is closed.
-
-The stomp configuration element can also be used to control how the destination 
-headers are parsed and interpreted.  The supported attributes are:
-  
-* `queue_prefix` : Defaults to `/queue/`
-* `topic_prefix` : Defaults to `/topic/`
-* `path_separator` : Defaults to `.`
-* `destination_separator` : Defaults to `,`
-* `any_child_wildcard` : Defaults to `*`
-* `regex_wildcard_start` : Defaults to `{`
-* `regex_wildcard_end` : Defaults to `}`
-* `any_descendant_wildcard` : Defaults to `**`
-
-It also supports nested `add_user_header` elements to more finely control how
-user headers are added to received STOMP messages.  The `add_user_header` element
-should contain the name of the header to set on the STOMP message.  It also 
-supports the following attributes:
-
-* `separator` : 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.
-* `kind` : The principle kind to look for.  Defaults to `*` (matches all 
-  principle kinds)
-
-Example:
-
-{pygmentize:: xml}
-<connector id="tcp" bind="tcp://0.0.0.0:61613">
-  <stomp max_header_length="10000">
-    <add_user_header separator=",">user</add_user_header>
-  </stomp>
-</connector>
-{pygmentize}
-
-
-### Client Libraries
-
-There are many open source STOMP clients for different platforms and
-languages.  You can find a full listing of available clients at:
-
-* [`http://stomp.github.com/implementations.html#Clients`](http://stomp.github.com/implementations.html#Clients)
-
-The ${project_name} distribution ships with an `examples` 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.
-
-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
-${project_name} specific features.
-
-### Connecting
-
-The default broker configuration secures access to the broker so that only
-the `admin` user can connect.  The default password for the `admin` user 
-is `password`.
-
-Example STOMP frame to connect to the broker:
-
-    CONNECT
-    
-    login:admin
-    passcode:password
-    
-    ^@
-
-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 `host_name` 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.
-
-### Destination Types
-
-${project_name} supports three types of destinations, queues, topics, and
-durable subscriptions.
-
-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.
-
-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.
-
-If you want to send or subscribe to a queue, topic, or durable
-subscription the STOMP destination should be prefixed with `/queue/`,
-`/topic/` or `/dsub/` respectively.
-
-Example STOMP frame sending to a queue:
-
-    SEND
-    destination:/queue/a
-
-    hello queue a
-    ^@
-
-### Topic Retained Messages
-
-If a message sent to a Topic has the `retain:set` 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:
-
-    SEND
-    destination:/topic/stock/IBM
-    retain:true
-
-    112.12
-    ^@
-
-You can also send a new message with the `retain:remove` header
-to have the topic forget about the last retained message.
-
-Note: retained messages are not retained between broker restarts.
-
-### Reliable Messaging
-
-${project_name} 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.
-
-To have a message be persistent, the sender must add the `persistent:true`
-header to the `SEND` STOMP frame.  Furthermore, if you are not sending the 
-message in a transaction, it is recommend that you also add a `receipt`
-header.  Once the broker responds with a `RECEIPT` frame correlated to 
-the send, you are guaranteed the broker will not drop the message even if
-a failure occurs.
-
-Example:
-
-    SEND
-    destination:/queue/a
-    receipt:001
-
-    hello queue a
-    ^@
-
-The client should not consider the send to have succeeded until he receives
-the correlated `RECEIPT` frame from the server.  Example:
-
-    RECEIPT
-    receipt-id:001
-    
-    ^@
-
-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 `RECEIPT` 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.
-
-You should only use subscribers which use the `client` or `client-individual`
-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.
-
-### Message Expiration
-
-${project_name} supports expiring old messages.  Unconsumed expired messages 
-are automatically removed from the queue.  You just need to specify when
-the message expires by setting the `expires` message header.  The expiration
-time must be specified as the number of milliseconds since the Unix epoch.
-
-Example:
-
-    SEND
-    destination:/queue/a
-    expires:1308690148000
-
-    this message will expire on Tue Jun 21 17:02:28 EDT 2011
-    ^@
-
-### Subscription Flow Control
-
-You can add a `credit` header to the `SUBSCRIBE` 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 `content-length` header. If either of the two credit windows have
-a positive value, the server will deliver messages to the client.
-
-The `credit` header value is expected to use the
-`count[,size]` syntax where:
-
- * count: initial setting of the credit window tracking the remaining number 
-   of messages that can be sent.  Must be specified.
- * 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.
-
-If the `credit` header is not specified it has the same effect
-as if it had been set to `credit:655360,655360`.  This setting allows the broker
-to optimally stream many small messages to the client or without overloading
-the clients processing buffers.
-
-As messages are sent from the server to the client, the credit windows are
-reduced by the corresponding amount. When the client send `ACK` frames to the 
-server, the credit windows are incremented by the number of messages and content 
-sizes corresponding to the messages that were acknowledged.
-
-Example:
-
-    SUBSCRIBE
-    id:mysub
-    destination:/queue/foo
-    credit:5,0
-    
-    ^@
-
-The above example would cause the subscription to only receive at most 5
-messages if the client is not sending any `ACK` messages back to the server.
-
-If you need to receive more messages without acknowledging them than the
-size of the credit window, you should use transactions and transactionally
-`ACK` 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.
-
-<!-- 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
-    
-    ^@
--->
-
-### Topic Durable Subscriptions
-
-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.
-
-To create or reattach to a a durable subscription with STOMP, you uniquely
-name the durable subscription using the `id` header on the `SUBSCRIBE` frame
-and also adding a `persistent:true` header. Example:
-
-    SUBSCRIBE
-    id:mysub
-    persistent:true
-    destination:/topic/foo
-    
-    ^@
-
-A standard `UNSUBSCRIBE` 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 `persistent:true` header to the
-`UNSUBSCRIBE` frame. Example:
-
-    UNSUBSCRIBE
-    id:mysub
-    persistent:true
-    
-    ^@
-
-If the durable subscription already exists you can address it directly using
-`/dsub/` prefix on the `destination` header. For example, send a message to
-the previously created `mysub` durable subscription, you send the following
-STOMP frame:
-
-
-    SEND
-    destination:/dsub/mysub
-
-    hello durable sub!
-    ^@
-
-Similarly, you can also subscribe to the subscription in the same way:
-
-    SUBSCRIBE
-    id:0
-    destination:/dsub/mysub
-    
-    ^@
-
-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 `destination` or `selector` header,
-then updates the original subscription, and the original connection will
-subsequently only receive messages matching the updated destination or
-selector.
-
-### Browsing Subscriptions
-
-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 `browser:true` header to the `SUBSCRIBE` frame. For example:
-
-    SUBSCRIBE
-    id:mysub
-    browser:true
-    destination:/queue/foo
-    
-    ^@
-
-Once the broker sends a browsing subscription the last message in the queue,
-it will send the subscription a special "end of browse" message to indicate
-browsing has completed and that the subscription should not expect any more
-messages. The "end of browse" message will have a `browser:end` header set.
-Example:
-
-    MESSAGE
-    subscription:mysub
-    destination:
-    message-id:
-    browser:end
-    
-    ^@
-
-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
-`browser-end:false` header to the `SUBSCRIBE` frame. When the
-`browser-end:false` header is added the subscription will not be sent the "end
-of browse" message previously described.
-
-### Queue Message Sequences
-
-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 `include-seq` header is added to the
-`SUBSCRIBE` frame. This header should be set to a header name which will be
-added messages delivered to hold value of the sequence number.
-
-Example:
-
-    SUBSCRIBE
-    id:mysub
-    destination:/queue/foo
-    include-seq:seq
-    
-    ^@
-
-Then you can expect to receive messages like:
-
-    MESSAGE
-    subscription:mysub
-    destination:/queue/foo
-    seq:1
-    
-    Hello
-    ^@
-    MESSAGE
-    subscription:mysub
-    destination:/queue/foo
-    seq:2
-    
-    World
-    ^@
-
-Furthermore, you can configure the `SUBSCRIBE` 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 `from-seq` header. Example:
-
-    SUBSCRIBE
-    id:mysub
-    destination:/queue/foo
-    from-seq:10
-    
-    ^@
-
-If the `from-seq` is set to `-1`, 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.
-
-Note: You can only use the `from-seq` 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.
-
-### Using Queue Browsers to Implement Durable Topic Subscriptions
-
-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.
-
-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:
-
- * consuming application records the last message sequence that 
-   was processed
- * message are not deleted when delivered to the subscriber
- * on restart consuming application continues receiving from the queue
-   for the last sequence that it received.
-
-The `SUBSCRIBE` frame used to create the browser should add the `include-seq`,
-`from-seq`, and `browser-end` 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 `from-seq` to:
-
- * `0` to start receiving at the head of the queue which sends
-   the subscription a copy of all the messages that are currently 
-   queued. 
- * `-1` 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.
-
-Example:
-
-    SUBSCRIBE
-    id:mysub
-    destination:/queue/foo
-    browser:true
-    browser-end:false
-    include-seq:seq
-    from-seq:0
-    
-    ^@
-
-Since this approach does not consume the messages from the queue, you should
-either:
-
-* Send messages to the queue with an expiration time so that they are 
-  automatically delete once the expiration time is reached.
-* Periodically run a normal consumer application which can cursor the queue
-  and delete messages are are deemed no longer needed.
-
-### Exclusive Subscriptions
-
-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.
-
-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.
-
-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.
-
-${project_name} 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.
-
-An exclusive subscription is created by adding a `exclusive:true` header
-to the `SUBSCRIBE` frame.  Example:
-
-    SUBSCRIBE
-    id:mysub
-    exclusive:true
-    destination:/queue/foo
-    
-    ^@
-
-### Temporary Destinations
-
-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:
-
-* `/temp-queue/` - For temporary queues.  Has the same delivery semantics as queues.
-* `/temp-topic/` - For temporary topics.  It has the same delivery semantics of topics.
-
-In a request/response scenario, you would first subscribe to the temporary topic:
-
-    SUBSCRIBE
-    id:mysub
-    destination:/temp-queue/example
-    
-    ^@
-
-Then you would send a request with the reply-to header set to the temporary destination. 
-Example:
-
-    SEND
-    destination:/queue/PO.REQUEST
-    reply-to:/temp-queue/example
-
-    PO145
-    ^@
-
-The consumer receiving the request will receive a message similar to:
-
-    MESSAGE
-    subscription:foo
-    reply-to:/queue/temp.default.23.example
-    destination:/queue/PO.REQUEST
-    reply-to:/temp-queue/example
-    
-    PO145
-
-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 (`/queue/temp.default.23.example` in the example above).
-
-Temporary destination names actually map to normal queues and topics. They just have
-a `temp.<broker_id>.<connection_id>.` prefix.  Any destination which starts with
-`temp.` 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.
-
-### Destination Wildcards
-
-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.
-
-* `.` is used to separate names in a path
-* `*` is used to match any name in a path
-* `{regex}` is used to match a path name against a regular expression.
-* `**` is used to recursively match path names
-
-For example imagine you are sending price messages from a stock exchange feed.
-You might use some kind of destination naming conventions such as:
-
-* `/topic/PRICE.STOCK.NASDAQ.IBM` to publish IBM's price on NASDAQ and
-* `/topic/PRICE.STOCK.NYSE.SUNW` to publish Sun's price on the New York Stock Exchange
-
-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.
-
-For example using the example above, these subscriptions are possible
-
-* `/topic/PRICE.**` : Any price for any product on any exchange
-* `/topic/PRICE.STOCK.**` : Any price for a stock on any exchange
-* `/topic/PRICE.STOCK.NASDAQ.*` : Any stock price on NASDAQ
-* `/topic/PRICE.STOCK.*.IBM` : Any IBM stock price on any exchange
-* `/topic/PRICE.STOCK.*.I*` : Any stock price starting with 'I' on any exchange
-* `/topic/PRICE.STOCK.*.*{[0-9]}` : Any stock price that ends in a digit on any exchange
-
-Destination wildcards can only be used in a SUBSCRIBE frame.
-
-### Composite Destinations
-
-You can use composite destinations to send or subscribe to multiple
-destinations at one time. You use separator of `,` between destination
-names.  For example, to send one message to 2 queues and 1 topic:
-
-    SEND
-    destination:/queue/a,/queue/b,/topic/c
-
-    Composites rock!
-    ^@
-
-### Message Selectors
-
-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.  
-
-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.
-
-Here is an example:
-
-    type = 'car' AND color = 'blue' AND weight > 2500
-
-To create a subscription with a message selector, you set the `selector`
-header in the STOMP `SUBSCRIBE` frame to the desired selector. Example:
-
-    SUBSCRIBE
-    id:sub0
-    selector:type = 'car' AND color = 'blue' AND weight > 2500
-    destination:/topic/foo
-    
-    ^@
-
-### Destination Name Restrictions
-
-Destination names are restricted to using the characters `a-z`, `A-Z`, `0-9`,
-`_`, `-` `%`, `~`, `:`, ' ', or `.` in addition to composite separator `,` and the wild
-card `*`.  Any other characters must be UTF-8 and then URL encoded if you wish to 
-preserve their significance.
+## Messaging Protocols Manuals
 
+* [STOMP Protocol Manual](stomp-manual.html)
+* [OpenWire Protocol Manual](openwire-manual.html) 

Modified: activemq/activemq-apollo/trunk/apollo-website/src/index.page
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/index.page?rev=1390773&r1=1390772&r2=1390773&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/index.page (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/index.page Wed Sep 26 23:12:26 2012
@@ -26,19 +26,14 @@ h1 Apollo #{project_version}
 reliable, easier to maintain messaging broker built from the foundations of
 the original [ActiveMQ]((http://activemq.apache.org). It accomplishes this
 using a radically different threading and message dispatching 
-[architecture](documentation/architecture.html). 
-
-In it’s current incarnation, Apollo only supports the STOMP protocol but just
-like the original ActiveMQ, it’s been designed to be a multi protocol broker.
-In future versions it will be adding OpenWire support so it can be compatible with
-ActiveMQ 5.x JMS clients.
+[architecture](documentation/architecture.html).  Like ActiveMQ, Apollo is a 
+multi-protocol broker and supports STOMP, Openwire, MQTT, SSL, and WebSockets.
 
 ## Features
 
-* [Stomp 1.0](http://stomp.github.com/stomp-specification-1.0.html) Protocol
-  Support
-* [Stomp 1.1](http://stomp.github.com/stomp-specification-1.1.html) Protocol
-  Support
+* [STOMP Protocol Support](documentation/stomp-manual.html) 
+* [OpenWire Protocol Support](documentation/openwire-manual.html)
+* MQTT Protocol Support
 * [Topics and Queues](documentation/user-manual.html#Destination_Types)
 * [Queue Browsers](documentation/user-manual.html#Browsing_Subscriptions)
 * [Durable Subscriptions on Topics](documentation/user-manual.html#Topic_Durable_Subscriptions)



Mime
View raw message