JBoss.org Community Documentation

- Prev
- Next

## Chapter 46. Interoperability

## 46.1. Stomp

Stomp is a text-orientated wire protocol that allows Stomp clients to communicate with Stomp Brokers.

Stomp clients are available for several languages and platforms making it a good choice for interoperability.

### 46.1.1. Native Stomp support

HornetQ provides native support for Stomp. To be able to send and receive Stomp messages, you must configure a `NettyAcceptor` with a `protocol` parameter set to `stomp`:

    <acceptor name="stomp-acceptor">
       <factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
       <param key="protocol"  value="stomp"/>
       <param key="port"  value="61613"/>
    </acceptor>

With this configuration, HornetQ will accept Stomp connections on the port `61613` (which is the default port of the Stomp brokers).

See the `stomp` example which shows how to configure a HornetQ server with Stomp.

#### 46.1.1.1. Flow control

When consuming messages in stomp, it's preferrable to use Acknowledge consumers, otherwise the server will send messages as fast as it can to the client (i.e. no flow control). Refer to the parameter stomp-consumer-credits for more information.

#### 46.1.1.2. Limitations

Message acknowledgements are not transactional. The ACK frame can not be part of a transaction (it will be ignored if its `transaction` header is set).

### 46.1.2. Mapping Stomp destinations to HornetQ addresses and queues

Stomp clients deals with destinations when sending messages and subscribing. Destination names are simply strings which are mapped to some form of destination on the server - how the server translates these is left to the server implementation.

In HornetQ, these destinations are mapped to addresses and queues. When a Stomp client sends a message (using a `SEND` frame), the specified destination is mapped to an address. When a Stomp client subscribes (or unsubscribes) for a destination (using a `SUBSCRIBE` or `UNSUBSCRIBE` frame), the destination is mapped to a HornetQ queue.

### 46.1.3. STOMP and connection-ttl

Well behaved STOMP clients will always send a DISCONNECT frame before closing their connections. In this case the server will clear up any server side resources such as sessions and consumers synchronously. However if STOMP clients exit without sending a DISCONNECT frame or if they crash the server will have no way of knowing immediately whether the client is still alive or not. STOMP connections therefore default to a connection-ttl value of 1 minute (see chapter on connection-ttl for more information. This value can be overridden using connection-ttl-override.

If you need a specific connection-ttl for your stomp connections without affecting the connection-ttl-override setting, you can configure your stomp acceptor with the "connection-ttl" property, which is used to set the ttl for connections that are created from that acceptor. For example:

    <acceptor name="stomp-acceptor">
       <factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
       <param key="protocol"  value="stomp"/>
       <param key="port"  value="61613"/>
       <param key="connection-ttl"  value="20000"/>
    </acceptor>

The above configuration will make sure that any stomp connection that is created from that acceptor will have its connection-ttl set to 20 seconds.

## Note

Please note that the STOMP protocol version 1.0 does not contain any heartbeat frame. It is therefore the user's responsibility to make sure data is sent within connection-ttl or the server will assume the client is dead and clean up server side resources. With `Stomp 1.1` users can use heart-beats to maintain the life cycle of stomp connections.

### 46.1.4. Stomp and JMS interoperabilty

#### 46.1.4.1. Using JMS destinations

As explained in Chapter 9, Mapping JMS Concepts to the Core API, JMS destinations are also mapped to HornetQ addresses and queues. If you want to use Stomp to send messages to JMS destinations, the Stomp destinations must follow the same convention:

- send or subscribe to a JMS Queue by prepending the queue name by `jms.queue.`.

  For example, to send a message to the `orders` JMS Queue, the Stomp client must send the frame:

      SEND
      destination:jms.queue.orders

      hello queue orders
      ^@

- send or subscribe to a JMS Topic by prepending the topic name by `jms.topic.`.

  For example to subscribe to the `stocks` JMS Topic, the Stomp client must send the frame:

      SUBSCRIBE
      destination:jms.topic.stocks

      ^@

#### 46.1.4.2. Sending and consuming Stomp message from JMS or HornetQ Core API

Stomp is mainly a text-orientated protocol. To make it simpler to interoperate with JMS and HornetQ Core API, our Stomp implementation checks for presence of the `content-length` header to decide how to map a Stomp message to a JMS Message or a Core message.

If the Stomp message does not have a `content-length` header, it will be mapped to a JMS TextMessage or a Core message with a single nullable SimpleString in the body buffer.

Alternatively, if the Stomp message has a `content-length` header, it will be mapped to a JMS BytesMessage or a Core message with a byte[] in the body buffer.

The same logic applies when mapping a JMS message or a Core message to Stomp. A Stomp client can check the presence of the `content-length` header to determine the type of the message body (String or bytes).

#### 46.1.4.3. Message IDs for Stomp messages

When receiving Stomp messages via a JMS consumer or a QueueBrowser, the messages have no properties like JMSMessageID by default. However this may bring some inconvenience to clients who wants an ID for their purpose. HornetQ Stomp provides a parameter to enable message ID on each incoming Stomp message. If you want each Stomp message to have a unique ID, just set the `stomp-enable-message-id` to true. For example:

    <acceptor name="stomp-acceptor">
       <factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
       <param key="protocol"  value="stomp"/>
       <param key="port"  value="61613"/>
       <param key="stomp-enable-message-id"  value="true"/>
    </acceptor>

When the server starts with the above setting, each stomp message sent through this acceptor will have an extra property added. The property key is `hq-message-id` and the value is a String representation of a long type internal message id prefixed with "`STOMP`", like:

      hq-message-id : STOMP12345

If `stomp-enable-message-id` is not specified in the configuration, default is `false`.

### 46.1.5. Stomp Over Web Sockets

HornetQ also support Stomp over Web Sockets. Modern web browser which support Web Sockets can send and receive Stomp messages from HornetQ.

To enable Stomp over Web Sockets, you must configure a `NettyAcceptor` with a `protocol` parameter set to `stomp_ws`:

    <acceptor name="stomp-ws-acceptor">
    	<factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
    	<param key="protocol" value="stomp_ws"/>
    	<param key="port" value="61614"/>
    </acceptor>

With this configuration, HornetQ will accept Stomp connections over Web Sockets on the port `61614` with the URL path `/stomp`. Web browser can then connect to `ws://<server>:61614/stomp` using a Web Socket to send and receive Stomp messages.

A companion JavaScript library to ease client-side development is available from GitHub (please see its documentation for a complete description).

The `stomp-websockets` example shows how to configure HornetQ server to have web browsers and Java applications exchanges messages on a JMS topic.

### 46.1.6. StompConnect

StompConnect is a server that can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API. Consequently, using StompConnect it is possible to turn HornetQ into a Stomp Broker and use any of the available stomp clients. These include clients written in C, C++, c# and .net etc.

To run StompConnect first start the HornetQ server and make sure that it is using JNDI.

Stomp requires the file `jndi.properties` to be available on the classpath. This should look something like:

    java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
    java.naming.provider.url=jnp://localhost:1099
    java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces

Make sure this file is in the classpath along with the StompConnect jar and the HornetQ jars and simply run `java org.codehaus.stomp.jms.Main`.

## 46.2. REST

Refer to HornetQ Rest Manual for more information.

- PrevChapter 45. Intercepting Operations
- Top of page
- Front page
- NextChapter 47. Performance Tuning