STOMP

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 Apache ActiveMQ Artemis, these destinations are mapped to addresses and queues depending on the operation being done and the desired semantics (e.g. anycast or multicast).

Incoming and outgoing STOMP frames can be logged by enabling DEBUG for org.apache.activemq.artemis.core.protocol.stomp.StompConnection. This can be extremely useful for debugging or simply monitoring client activity. Along with the STOMP frame itself the remote IP address of the client is logged as well as the internal connection ID so that frames from the same client can be correlated.

Follow these steps to configure logging appropriately.

The STOMP specification is intentionally ambiguous about message routing semantics. When providing an overview of the protocol the STOMP 1.2 specification says:

Therefore, there are a handful of different ways to specify which semantics are desired both on the client-side and broker-side.

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 the connection-ttl-override property or if you need a specific connectionTtl for your stomp connections without affecting the broker-wide connection-ttl-override setting, you can configure your stomp acceptor with the connectionTtl property, which is used to set the ttl for connections that are created from that acceptor. For example:

The above configuration will make sure that any STOMP connection that is created from that acceptor and does not include a heart-beat header or disables client-to-server heart-beats by specifying a 0 value will have its connection-ttl set to 20 seconds. The connectionTtl set on an acceptor will take precedence over connection-ttl-override. The default connectionTtl is 60,000 milliseconds.

Since STOMP 1.0 does not support heart-beating then all connections from STOMP 1.0 clients will have a connection TTL imposed upon them by the broker based on the aforementioned configuration options. Likewise, any STOMP 1.1 or 1.2 clients that don’t specify a heart-beat header or disable client-to-server heart-beating (e.g. by sending 0,X in the heart-beat header) will have a connection TTL imposed upon them by the broker.

For STOMP 1.1 and 1.2 clients which send a non-zero client-to-server heart-beat header value then their connection TTL will be set accordingly. However, the broker will not strictly set the connection TTL to the same value as the specified in the heart-beat since even small network delays could then cause spurious disconnects. Instead, the client-to-server value in the heart-beat will be multiplied by the heartBeatToConnectionTtlModifier specified on the acceptor. The heartBeatToConnectionTtlModifier is a decimal value that defaults to 2.0 so for example, if a client sends a heart-beat header of 1000,0 the connection TTL will be set to 2000 so that the data or ping frames sent every 1000 milliseconds will have a sufficient cushion so as not to be considered late and trigger a disconnect. This is also in accordance with the STOMP 1.1 and 1.2 specifications which both state, "because of timing inaccuracies, the receiver SHOULD be tolerant and take into account an error margin."

The minimum and maximum connection TTL allowed can also be specified on the acceptor via the connectionTtlMin and connectionTtlMax properties respectively. The default connectionTtlMin is 1000 and the default connectionTtlMax is Java’s Long.MAX_VALUE meaning there essentially is no max connection TTL by default. Keep in mind that the heartBeatToConnectionTtlModifier is relevant here. For example, if a client sends a heart-beat header of 20000,0 and the acceptor is using a connectionTtlMax of 30000 and a default heartBeatToConnectionTtlModifier of 2.0 then the connection TTL would be 40000 (i.e. 20000 * 2.0) which would exceed the connectionTtlMax. In this case the server would respond to the client with a heart-beat header of 0,15000 (i.e. 30000 / 2.0). As described previously, this is to make sure there is a sufficient cushion for the client heart-beats in accordance with the STOMP 1.1 and 1.2 specifications. The same kind of calculation is done for connectionTtlMin.

The minimum server-to-client heart-beat value is 500ms.

STOMP subscribers can specify an expression used to select or filter what the subscriber receives using the selector header. The filter expression syntax follows the core filter syntax described in the Filter Expressions documentation.

The SUBSCRIBE and UNSUBSCRIBE frames can be augmented with special headers to create and destroy durable subscriptions respectively.

To create a durable subscription the client-id header must be set on the CONNECT frame and the durable-subscription-name must be set on the SUBSCRIBE frame. The combination of these two headers will form the identity of the durable subscription.

To delete a durable subscription the client-id header must be set on the CONNECT frame and the durable-subscription-name must be set on the UNSUBSCRIBE frame. The values for these headers should match what was set on the SUBSCRIBE frame to delete the corresponding durable subscription.

Aside from durable-subscription-name, the broker also supports durable-subscriber-name (a deprecated property used before durable-subscription-name) as well as activemq.subscriptionName from ActiveMQ "Classic". This is the order of precedence if the frame contains more than one of these:

1) durable-subscriber-name 2) durable-subscription-name 3) activemq.subscriptionName

It is possible to pre-configure durable subscriptions since the STOMP implementation creates the queue used for the durable subscription in a deterministic way (i.e. using the format of client-id.subscription-name). For example, if you wanted to configure a durable subscription on the address myAddress with a client-id of myclientid and a subscription name of mysubscription then configure the durable subscription:

STOMP clients may send very large frame bodies which can exceed the size of the broker’s internal buffer, causing unexpected errors. To prevent this situation from happening, the broker provides a STOMP configuration attribute stompMinLargeMessageSize. This attribute can be configured inside a stomp acceptor, as a parameter. For example:

The type of this attribute is integer. When this attributed is configured, the broker will check the size of the body of each STOMP frame arrived from connections established with this acceptor. If the size of the body is equal or greater than the value of stompMinLargeMessageSize, the message will be persisted as a large message. When a large message is delivered to a STOMP consumer, the broker will automatically handle the conversion from a large message to a normal message, before sending it to the client.

If a large message is compressed, the server will uncompressed it before sending it to stomp clients. The default value of stompMinLargeMessageSize is the same as the default value of minLargeMessageSize.

Apache ActiveMQ Artemis also supports STOMP over Web Sockets. Modern web browsers which support Web Sockets can send and receive STOMP messages.

STOMP over Web Sockets is supported via the normal STOMP acceptor:

With this configuration, Apache ActiveMQ Artemis will accept STOMP connections over Web Sockets on the port 61614. Web browsers can then connect to ws://<server>:61614 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 payload length of Web Socket frames can vary between client implementations. By default the broker will accept frames with a payload length of 65,536. If the client needs to send payloads longer than this in a single frame this length can be adjusted by using the webSocketMaxFramePayloadLength URL parameter on the acceptor. In previous version this was configured via the similarly named stompMaxFramePayloadLength acceptor URL parameter.

Web Socket frames can be encoded as either binary or text. By default the broker encodes them as binary. However, this can be changed by using the webSocketEncoderType acceptor URL parameter. Valid values are binary and text.

The stomp-websockets example shows how to configure an Apache ActiveMQ Artemis broker to have web browsers and Java applications exchanges messages.

STOMP clients can use the consumer-window-size header on the SUBSCRIBE frame to control the flow of messages to clients. This is broadly discussed in the Flow Control chapter.

This ability is similar to the activemq.prefetchSize header supported by ActiveMQ "Classic". However, that header specifies the size in terms of messages whereas consumer-window-size specifies the size in terms of bytes. ActiveMQ Artemis supports the activemq.prefetchSize header for backwards compatibility but the value will be interpreted as bytes just like consumer-window-size would be. If both activemq.prefetchSize and consumer-window-size are set then the value for consumer-window-size will be used.

Setting consumer-window-size to 0 will ensure that once a STOMP client receives a message that it will not receive another one until it sends the appropriate ACK or NACK frame for the message it already has.

Setting consumer-window-size to a value greater than 0 will allow it to receive messages until the cumulative bytes of those messages reaches the configured size. Once that happens the client will not receive any more messages until it sends the appropriate ACK or NACK frame for the messages it already has.

Setting consumer-window-size to -1 means there is no flow control and the broker will dispatch messages to clients as fast as it can.

Flow control can be configured at the acceptor as well using the stompConsumerWindowSize URL parameter. This value is 10240 (i.e. 10K) by default for clients using client and client-individual acknowledgement modes. It is -1 for clients using the auto acknowledgement mode. Even if stompConsumerWindowSize is set on the STOMP acceptor it will be overriden by the value provided by individual clients using the consumer-window-size header on their SUBSCRIBE frame.

Using the DEBUG logging mentioned earlier it is possible to see the size of the MESSAGE frames dispatched to clients. This can help when trying to determine the best consumer-window-size setting.