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:
Registration with the Message Queue Port Mapper service so that STOMP clients can discover the service dynamically
Support for TCP and SSL/TLS connections, including SSL/TLS connections requiring client authentication
Automatic conversion of STOMP frame messages to and from JMS BytesMessage and TextMessage types
Extensible message handling and transformation (by defining a custom message transformer)
Support for the full STOMP protocol, including the STOMP JMS bindings
The following subsections provide information about the STOMP bridge and how to configure and manage it:
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. |
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.
Confirm that the bridge service manager is enabled.
See To Enable the Bridge Service Manager for instructions.
Add the name stomp to the list of bridge names in the imq.bridge.activelist broker property.
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 |
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 |
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:
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.
If a custom message transformer is defined for the bridge, pass the JMS message to the transformer's MessageTransformer.transform() method.
Send the message to its destination.
For JMS messages sent to a STOMP client, the STOMP bridge performs these tasks:
If a custom message transformer is defined for the bridge, pass the JMS message to the transformer's MessageTransformer.transform() method.
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.
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.
Send the message to the STOMP client.
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:
The formal parameters T and S must be of type javax.jms.Message.
" The source and target arguments will be either "STOMP" and "SUN_MQ" or "SUN_MQ" and "STOMP", respectively.
A source argument value of "STOMP" indicates that the message argument is from a STOMP client SEND frame received by the STOMP bridge.
A source argument value of "SUN_MQ" indicates that the message argument is from a Message Queue destination.
The readOnly argument will be false if the source argument is "STOMP" and true if the source argument is "SUN_MQ".
If the source argument is "STOMP", the properties argument contains, as key/value pairs, any arbitrary user headers that the STOMP bridge was unable to convert to JMS message properties in the message argument. Otherwise, the properties argument is null.
The charsetName argument should be ignored unless the source argument is "STOMP" and the message argument is a JMS BytesMessage message. This combination of argument values indicates that the message is from a STOMP client and has already been converted to a BytesMessage message.
The returned message must be in write-only mode if the source argument is "STOMP" and in read-only mode if the source argument is "SUN_MQ".
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