Stomp

ActiveMQ supports the Stomp protocol. This makes it easy to write a client in pure Ruby, Perl, Python or PHP for working with ActiveMQ.

Please see the Stomp site for more details

Enabling the ActiveMQ Broker for Stomp

Its very easy to enable ActiveMQ for Stomp. Just add a connector to the broker using the stomp URL.

<connector>
      <serverTransport uri="stomp://localhost:61626"/>
    </connector>

Of course use any host name and port you like.

To see a full example, try this XML. If you save this XML as foo.xml then you can run stomp via the command line as

activemq xbean:foo.xml

For more help see Run Broker.

Working with Destinations with Stomp

Note that the prefix in stomp /queue/ or /topic/ is removed from the string before passing it to ActiveMQ as a JMS destination. Also note that the default separator in MOM systems is . (DOT). So FOO.BAR is the normal syntax of a MOM queue - the Stomp equivalent would be */queue/FOO.BAR*

Be careful about starting destinations with /

If in Stomp world you use /queue/foo/bar then in a JMS world the queue would be called foo/bar not /foo/bar.

Working with JMS Text/Bytes Messages and Stomp

Stomp is a very simple protocol - that's part of the beauty of it! As such, it does not have knowledge of JMS messages such as TextMessages or BytesMessages. The protocol does however support a content-length header. To provide more robust interaction between Stomp and JMS clients, ActiveMQ keys off of the inclusion of this header to determine what message type to create when sending from Stomp to JMS. The logic is simple:

Inclusion of content-length header	Resulting Message
yes	BytesMessage
no	TextMessage

This same logic can be followed when going from JMS to Stomp, as well. A Stomp client could be written to key off of the inclusion of the content-length header to determine what type of message structure to provide to the user.

Using JMS semantics with Stomp

Note that Stomp is designed to be as simple as possible - so any scripting language / platform can message any other with minimal effort.

Stomp allows pluggable headers on each request such as sending & receiving messages. These custom headers can then be used inside JMS selectors used in any client of ActiveMQ (Stomp or OpenWire)

In addition Stomp supports the following standard JMS properties

Stomp header	JMS header	Description
correlation-id	JMSCorrelationID	good consumes will add this header to any responses they send
expires	JMSExpiration	the expiration time of the message
persistent	JMSDeliveryMode	whether or not the message is persistent
priority	JMSPriority	the priority on the message
reply-to	JMSReplyTo	the destination you should send replies to
type	JMSType	sets the type of the message
JMSXGroupID	JMSXGroupID	for specifying the Message Groups
JMSXGroupSeq	JMSXGroupSeq	an optional header for specifying the sequence number in the Message Groups

ActiveMQ extensions to Stomp

You can add custom headers to Stomp commands to configure the ActiveMQ protocol. Here are some examples

Verb	Header	Type	Description
CONNECT	client-id	string	Specifies the JMS Client ID which is used in combination to the activemqq.subscriptionName to denote a durable subscriber
SUBSCRIBE	selector	string	Specifies a JMS Selector using SQL 92 syntax as specified in the JMS 1.1 specificiation. This allows a filter to be applied to each message as part of the subscription.
SUBSCRIBE	activemq.dispatchAsync	boolean	Should messages be dispatched synchronously or asynchronously from the producer thread for non-durable topics in the broker. For fast consumers set this to false. For slow consumers set it to true so that dispatching will not block fast consumers.
SUBSCRIBE	activemq.exclusive	boolean	Would I like to be an Exclusive Consumer on a queue
SUBSCRIBE	activemq.maximumPendingMessageLimit	int	For Slow Consumer Handlingon non-durable topics by dropping old messages - we can set a maximum pending limit which once a slow consumer backs up to this high water mark we begin to discard old messages
SUBSCRIBE	activemq.noLocal	boolean	Specifies whether or not locally sent messages should be ignored for subscriptions. Set to true to filter out locally sent messages
SUBSCRIBE	activemq.prefetchSize	int	Specifies the maximum number of pending messages that will be dispatched to the client. Once this maximum is reached no more messages are dispatched until the client acknowledges a message. Set to 1 for very fair distribution of messages across consumers where processing messages can be slow
SUBSCRIBE	activemq.priority	byte	Sets the priority of the consumer so that dispatching can be weighted in priority order
SUBSCRIBE	activemq.retroactive	boolean	For non-durable topics do you wish this subscription to the retroactive.
SUBSCRIBE	activemq.subscriptionName	string	For durable topic subscriptions you must specify the same clientId on the connection and subscriberName on the subscribe