Sun GlassFish Message Queue 4.4 Administration Guide

Configuring and Managing STOMP Bridge Services

The STOMP (Streaming Text Oriented Messaging Protocol) open source project at http://stomp.codehaus.org defines a simple wire protocol that clients written in any language can use to communicate with any messaging provider that supports the STOMP protocol.

Message Queue 4.4 provides support for the STOMP protocol through the STOMP bridge service. This service enables a Message Queue broker to communicate with STOMP clients.

The STOMP bridge service provides the features needed to fully integrate STOMP messaging into the JMS messaging environment of Message Queue:

The following subsections provide information about the STOMP bridge and how to configure and manage it:

Configuring the STOMP Bridge

To configure the STOMP bridge, you specify several imq.bridge.stomp broker properties in the broker hosting the bridge. These properties, which control the various features of the STOMP bridge, are listed in Table 12–10.

Table 12–10 Broker Properties for the STOMP Bridge Service

Property 

Type 

Default Value 

Description 

imq.bridge.stomp.tcp.enabled

Boolean 

true

Does the STOMP bridge accept TCP connections? 

imq.bridge.stomp.tcp.port

Integer 

7672

The port on which the STOMP bridge listens for TCP connections, provided that imq.bridge.stomp.tcp.enabled is true.

imq.bridge.stomp.tls.enabled

Boolean 

false

Does the STOMP bridge accept SSL/TLS connections? 

If true, a keystore must be created using the imqkeytool utility before starting the broker.

imq.bridge.stomp.tls.port

Integer 

7673

The port on which the STOMP bridge listens for SSL/TLS connections, provided that imq.bridge.stomp.tls.enabled is true.

imq.bridge.stomp.tls.requireClientAuth

Boolean 

false

Do SSL/TLS connections require client authentication? 

imq.bridge.stomp.consumerFlowLimit

Integer 

1000

The maximum number of unacknowledged messages that the STOMP bridge will deliver on a transacted STOMP subscription. The STOMP client must then acknowledge the messages and commit the transaction. 

imq.bridge.stomp.messageTransformer

String 

None 

The fully qualified class name of a class that extends the Message Queue bridge MessageTransformer abstract class (with formal type parameters as javax.jms.Message). Place this class under the IMQ_HOME/lib/ext directory.

imq.bridge.stomp.logfile.limit

Integer 

0

The approximate maximum number of bytes the STOMP bridge writes to any one log file. 

A value of 0 (zero) indicates that there is no maximum limit.

imq.bridge.stomp.logfile.count

Integer 

1

The number of log files the STOMP bridge cycles through. 

Starting and Stopping the STOMP Bridge

The STOMP bridge is started automatically when the broker hosting the bridge starts. Similarly, the STOMP bridge is stopped automatically when the broker hosting it is stopped. The STOMP bridge can be stopped and restarted manually using the imqbridgemgr utility.

ProcedureTo Activate the STOMP Bridge

  1. Confirm that the bridge service manager is enabled.

    See To Enable the Bridge Service Manager for instructions.

  2. Add the name stomp to the list of bridge names in the imq.bridge.activelist broker property.

ProcedureTo Stop the STOMP Bridge Manually

  1. Enter the imqbridgemgr stop bridge command, specifying the bridge type and the broker.

    For example, to stop the STOMP bridge hosted by the broker running on myhost:8886, enter this command:


    imqbridgemgr stop bridge -t STOMP -b myhost:8886

ProcedureTo Start the STOMP Bridge Manually

  1. Enter the imqbridgemgr start bridge command, specifying the bridge type and the broker.

    For example, to start the STOMP bridge hosted by the broker running on myhost:8886, enter this command:


    imqbridgemgr start bridge -t STOMP -b myhost:8886

Message Processing Sequence Across the STOMP Bridge

The STOMP bridge processes messages differently depending on whether the message is a STOMP frame message being received from a STOMP client or a JMS message being sent to a STOMP client.

For STOMP frame messages received from a STOMP client, the STOMP bridge performs these tasks:

  1. Convert the STOMP frame message to a JMS BytesMessage if the content-length header is present; otherwise, convert it to a JMS TextMessage using UTF-8 as the message encoding.

  2. If a custom message transformer is defined for the bridge, pass the JMS message to the transformer's MessageTransformer.transform() method.

  3. Send the message to its destination.

For JMS messages sent to a STOMP client, the STOMP bridge performs these tasks:

  1. If a custom message transformer is defined for the bridge, pass the JMS message to the transformer's MessageTransformer.transform() method.

  2. If the transformed message (or original message when no custom transformer is defined) is not a JMS TextMessage or JMS BytesMessage message, close the STOMP connection and stop processing the message.

  3. Convert the JMS message to a STOMP frame message, using UTF-8 encoding for all headers and for the message body of a JMS TextMessage message.

  4. Send the message to the STOMP client.

Message Transformation During Message Processing

The message transformation between STOMP frame messages and JMS messages that the STOMP bridge automatically provides is sufficient in most applications. However, if you need to perform special processing or to send JMS message types other than BytesMessage or TextMessage to STOMP clients, you can define a custom message transformer for the STOMP bridge.

This custom message transformer is a Java class that extends the Message Queue Bridge MessageTransformer abstract class by implementing the class's transform() method. Then, place the class file in the IMQ_HOME/lib/ext directory and set the imq.bridge.stomp.messageTransformer broker property of the broker hosting the STOMP bridge to the fully qualified class name of the class.

When implementing the transform() method, keep these points in mind:

STOMP Protocol Features and the STOMP Bridge

The STOMP bridge supports the full STOMP protocol, including all additional STOMP headers for the STOMP JMS bindings, as listed at http://stomp.codehaus.org/Stomp+JMS.

The following table clarifies how the STOMP bridge handles certain command and header combinations that might be otherwise be subject to multiple interpretations.

Table 12–11 STOMP Bridge Handling of Selected Command/Header Combinations

STOMP Frame Command 

STOMP Frame Header 

Handling by the STOMP Bridge 

CONNECT

login

passcode

The STOMP bridge requires these headers to be specified; otherwise, it returns an ERROR frame.

SEND

SUBSCRIBE

UNSUBSCRIBE

MESSAGE

destination

MQ STOMP bridge interprets prefixes in destination header values as follows:

  • /queue/: the prefix is followed by the name of a Queue

  • /topic/: the prefix is followed by the name of a Topic

  • /temp-queue/: the prefix is followed by the name of a TemporaryQueue

  • /temp-topic/: the prefix is followed by the name of a TemporaryTopic

Note that the following two prefixes are reserved to be used only for send reply messages to a MESSAGE frame's replyto destination, and should only be used in the same CONNECT session in which the MESSAGE is received.

  • /temp-queue/temporary_destination://queue/

  • /temp-topic/temporary_destination://topic/

SEND

expires

priority

persistent

When these headers are not specified for SEND, the message will be sent with the same default values as for a Message Queue Java client.

SEND

user specific headers 

On SEND, a user can specify additional headers beyond the ones specified in the STOMP protocol and STOMP JMS Bindings. These headers are transformed to String properties of the converted JMS message. Therefore, the keys for these headers must be valid JMS property names. If any are not, and a custom message transformer is specified for STOMP bridge, the invalid ones are passed in the properties argument to the transformer's transform() method.

SUBSCRIBE

selector

Supported as described in the STOMP JMS Bindings on SUBSCRIBE.

SUBSCRIBE

id

A STOMP client should always specify an id header for SUBSCRIBE. If no "id" header is specified, the STOMP bridge assigns it a default value of /subscription-to/STOMP-destination-name.

All SUBSCRIBE id values must be unique in the scope of the STOMP client connection to the STOMP bridge; otherwise, an ERROR frame will be returned.

SUBSCRIBE

transaction

For a STOMP subscription to receive messages in a transaction, the SUBSCRIBE frame must specify a transaction header with a transaction identifier whose transaction state is started. If the transaction does not exist, an ERROR frame is returned. After the transaction completes (using either COMMIT or ABORT), message delivery to the transacted subscription is paused until the next transaction BEGIN.

ABORT

transaction

For transacted subscriptions, aborting a transaction will cause the STOMP bridge to stop message delivery to all transacted subscriptions in the CONNECT session. Then, upon the next BEGIN, the STOMP bridge restarts the message delivery sequence to all the transacted subscriptions in the CONNECT session, including all unconsumed messages that had been previously delivered.

SUBSCRIBE

ack

For STOMP ack:auto (the default), a subscribed message is considered acknowledged as soon as it is sent to the STOMP client.

UNSUBSCRIBE

durable-subscriber-name

Unsubscribes a durable subscription, with these provisions: 

  • destination and id headers, if specfied, are ignored.

  • An ERROR frame is returned if the connection (CONNECT) has no client-id.

If an active subscriber with the durable name exists on the connection, it is first closed, and then the durable subscriber is unsubscribed.  

BEGIN

transaction

Transactions are at STOMP CONNECT session level. Nested transactions are not supported. On attempts to start a nested transaction, an ERROR frame is returned.

The transaction identifier will also be used for SUBSCRIBE frame to create a transacted subscription.

ACK

subscription

ACK should always specify a subscription header specifying the subscription id that the message to be acked was delivered to.

If a subcriber id is not specified, the STOMP bridge default subscription id prefix is used to find the first matching subscription id with the prefix to ack the message. 

If the subscription for the specified subscription id was not created as transacted, and a transaction header is specified for the ACK, an ERROR frame is returned;

ACK on a message ID, if found, will ACK all earlier messages delivered to the subscription in addition to the message with the given message ID.

ACK

transaction

For transacted subscription, an ACK for a message ID automatically ACKs all ealier messages sent to the transacted subscription in addition to the message with the given message ID. For transacted subscription, a message is considered consumed only when it is explicitly or implicitly ACKed in a transaction and there is a subsequent successful COMMIT on that transaction. If the transaction header is not specified but the subscription header is specified and the subscription is a transacted subscription, the message is ACKed in the current transaction if there is a current transaction. If there is no current transaction, an ERROR frame is returned.

MESSAGE

ERROR

content-length

The STOMP bridge always sets the content-length header for MESSAGE and ERROR frames sent to STOMP clients.

SEND

MESSAGE

reply-to

The STOMP bridge permits SEND from different STOMP CONNECT sessions as well as from the same CONNECT session to send reply messages to a STOMP reply-to header of temporary destination:

  • In the same CONNECT session, when SUBSCRIBE and SEND reply, use the same temporary destination string that is used in the SEND's reply-to header.

  • In a different CONNECT session, upon receiving a MESSAGE with a reply-to header of a temporary destination, use the same temporary destination string in the MESSAGE's reply-to header to SEND a reply to the reply-to temporary destination. This technique can also be used for sending the reply message when in the same CONNECT session.