This section describes the format of Stomp data packets , as well as the semantics of the data packet exchanges. Stomp is a relatively simple wire protocol—it is even possible to communicate manually with a Stomp broker using a telnet client (see Stomp Tutorial ).

In principal, Stomp can be combined with any transport protocol, including connection-oriented and non-connection-oriented transports. In practice, though, Stomp is usually implemented over TCP and this is the only transport currently supported by Fuse Message Broker.

The Stomp specification is licensed under the Creative Commons Attribution v2.5

The Stomp specification defines the term frame to refer to the data packets transmitted over a Stomp connection. A Stomp frame has the following general format:

<StompCommand>
<HeaderName_1>:<HeaderValue_1>
<HeaderName_2>:<HeaderValue_2>
    
<FrameBody>
^@

A Stomp frame always starts with a Stomp command (for example, SEND) on a line by itself. The Stomp command may then be followed by zero or more header lines: each header is in a <key>:<value> format and terminated by a newline. A blank line indicates the end of the headers and the beginning of the body, <FrameBody>, (which is empty for many of the commands). The frame is terminated by the null character, which is represented as ^@ above (Ctrl-@ in ASCII)).

Most Stomp commands have oneway semantics (that is, after sending a frame, the sender does not expect any reply). The only exceptions are:

Any client frame, other than CONNECT, may specify a receipt header with an arbitrary value. This causes the server to acknowledge receipt of the frame with a RECEIPT frame, which contains the value of this header as the value of the receipt-id header in the RECEIPT frame. For example, the following frame shows a SEND command that includes a receipt header:

SEND
destination:/queue/a
receipt:message-12345
 
Hello a!^@

Table 7 lists the client commands for the Stomp protocol. The Reply column indicates whether or not the server sends a reply frame by default.

After opening a socket to connect to the remote server, the client sends a CONNECT command to initiate a Stomp session. For example, the following frame shows a typical CONNECT command, including a login header and a passcode header:

CONNECT
login: <username>
passcode:<passcode>
 
^@

After the client sends the CONNECT frame, the server always acknowledges the connection by sending a frame, as follows:

CONNECTED
session: <session-id> 
 
^@

The session-id header is a unique identifier for this session (currently unused).

The SEND command sends a message to a destination—for example, a queue or a topic—in the messaging system. It has one required header, destination, which indicates where to send the message. The body of the SEND command is the message to be sent. For example, the following frame sends a message to the /queue/a destination:

SEND
destination:/queue/a
hello queue a
 
^@

From the client’s perspective, the destination name, /queue/a, is an arbitrary string. Despite seeming to indicate that the destination is a queue it does not, in fact, specify any such thing. Destination names are simply strings that are mapped to some form of destination on the server; how the server translates these strings is up to the implementation.

The SEND command also supports the following optional headers:

The SUBSCRIBE command registers a client’s interest in listening to a specific destination. Like the SEND command, the SUBSCRIBE command requires a destination header. Henceforth, any messages received on the subscription are delivered as MESSAGE frames, from the server to the client. For example, the following frame shows a client subscribing to the destination, /queue/a:

SUBSCRIBE
destination: /queue/foo
ack: client
 
^@

In this case the ack header is set to client, which means that messages are considered delivered only after the client specifically acknowledges them with an ACK frame. The body of the SUBSCRIBE command is ignored.

The SUBSCRIBE command supports the following optional headers:

The UNSUBSCRIBE command removes an existing subscription, so that the client no longer receives messages from that destination. It requires either a destination header or an id header (if the previous SUBSCRIBE operation passed an id value). For example, the following frame cancels the subscription to the /queue/a destination:

UNSUBSCRIBE
destination: /queue/a
 
^@

The ACK command acknowledges the consumption of a message from a subscription. If the client issued a SUBSCRIBE frame with an ack header set to client, any messages received from that destination are not considered to have been consumed until the message is acknowledged by an ACK frame.

The ACK command has one required header, message-id, which must contain a value matching the message-id for the MESSAGE being acknowledged. Optionally, a transaction header may be included, if the acknowledgment participates in a transaction. For example, the following frame acknowledges a message in the context of a transaction:

ACK
message-id: <message-identifier>
transaction: <transaction-identifier>
 
^@

The BEGIN command initiates a transaction. Transactions can be applied to SEND and ACK commands. Any messages sent or acknowledged during a transaction can either be commited or rolled back at the end of the transaction.

BEGIN
transaction: <transaction-identifier>
 
^@

The transaction header is required and the <transaction-identifier> can be included in SEND, COMMIT, ABORT, and ACK frames to bind them to the named transaction.

The COMMIT command commits a specific transaction.

COMMIT
transaction: <transaction-identifier>
 
^@

The transaction header is required and specifies the transaction, <transaction-identifier>, to commit.

The ABORT command rolls back a specific transaction.

ABORT
transaction: <transaction-identifier>
 
^@

The transaction header is required and specifies the transaction, <transaction-identifier>, to roll back.

The DISCONNECT command disconnects gracefully from the server.

DISCONNECT
 
^@

Table 8 lists the commands that the server can send to a Stomp client. These commands all have oneway semantics.

The MESSAGE command conveys messages from a subscription to the client. The MESSAGE frame must include a destination header, which identifies the destination from which the message is taken. The MESSAGE frame also contains a message-id header with a unique message identifier. The frame body contains the message contents. For example, the following frame shows a typical MESSAGE command with destination and message-id headers:

MESSAGE
destination:/queue/a
message-id: <message-identifier>
 
hello queue a^@

The MESSAGE command supports the following optional headers:

A RECEIPT frame is issued from the server whenever the client requests a receipt for a given command. The RECEIPT frame includes a receipt-id, containing the value of the receipt-id from the original client request. For example, the following frame shows a typical RECEIPT command with receipt-id header:

RECEIPT
receipt-id:message-12345
 
^@

The receipt body is always empty.

The server may send ERROR frames if something goes wrong. The error frame should contain a message header with a short description of the error. The body may contain more detailed information (or may be empty). For example, the following frame shows an ERROR command with a non-empty body:

ERROR
message: malformed packet received
 
The message:
-----
MESSAGE
destined:/queue/a
Hello queue a!
-----
Did not contain a destination header, which is required for message
propagation.
^@

The ERROR command supports the following optional headers: