STOMP

If you find that this library lacks some feature you need, or you have a suggestion for improving it, please don’t hesitate to get in touch with me!

1 Introduction

This library implements the STOMP protocol, both the codec for STOMP frames and the session protocol used by clients.

The STOMP specification includes a lot of important information that’s needed to make sense of the definitions below, including such things as

• what a "destination" is

• how to correctly acknowledge messages received from the server

• how to arrange for acknowledgements-of-receipt from the server

• how to manage transactions

1.1 Destinations

When using RabbitMQ with its STOMP plugin as your STOMP server, the available destinations are

• (string-append "/queue/" queue-name) — When used with stomp-send, delivers a message directly to the named queue. When used with stomp-subscribe, consumes from the named queue (at which point it’s interesting to think about which ack-mode you want to use).

• (string-append "/exchange/" exchange-name "/" routing-key) — When used with stomp-send, delivers a message via the named exchange, using the given routing-key. When used with stomp-subscribe, creates an anonymous queue, binds it to the named exchange using routing-key as a binding pattern, and starts consuming from the anonymous queue.

ActiveMQ and other STOMP message brokers have different destination name schemata and routing behaviours.

2 License

All the code in this package is licensed under the LGPL, version 3.0 or any later version. See the licence text for full details.

3 Changes

Version 3.0 of this library changes the interface to many of the main API procedures, generally relying more on keyword arguments and less on positional arguments.

4 Examples

In the examples below, I’ll make use of the RabbitMQ demonstration broker service.

4.1 Sending a message

(require stomp)

(define s (stomp-connect "dev.rabbitmq.com"

#:login "guest"

#:passcode "guest"

#:virtual-host "/"))

(stomp-send s "/exchange/amq.rabbitmq.log/info"

(string->bytes/utf-8 "Hello world, from Racket!"))

(stomp-disconnect s)

4.2 Sending a message, with a receipt

(require stomp)

(define s (stomp-connect "dev.rabbitmq.com"

#:login "guest"

#:passcode "guest"

#:virtual-host "/"))

(call-with-receipt s

(lambda (receipt)

(stomp-send s "/exchange/amq.rabbitmq.log/info"

(string->bytes/utf-8 "Hello world, from Racket!")

#:headers `((receipt ,receipt)))))

; At this point, we know the server has received our

; SEND, because we have received its RECEIPT frame. See

; the STOMP specification for details of what exact

; implications this has for whether the server has

; processed the SEND or not.

(stomp-disconnect s)

4.3 Subscribing to an exchange

This example uses RabbitMQ’s AMQP "wildcards" to subscribe to all messages travelling through the "amq.rabbitmq.log" exchange.

(require stomp)

(define s (stomp-connect "dev.rabbitmq.com"

#:login "guest"

#:passcode "guest"

#:virtual-host "/"))

(stomp-subscribe s "/exchange/amq.rabbitmq.log/#" "my-subscription")

(let loop ()

(let ((m (stomp-next-message s "my-subscription")))

(pretty-print m)

(loop)))

5 API

• command — The STOMP command part of the frame. For frames received from the server, this will usually be "MESSAGE". Frames sent to the server are usually constructed using the procedures described below (in particular stomp-send).

• headers — The STOMP headers sent or received with the frame. See the STOMP specification for details of the meaning of various headers.

• body — The body sent or received with the frame. This is entirely application-specific: STOMP makes no restrictions on the length or format of the body part of a frame. Note that it is a byte vector, however: make sure to use string->bytes/utf-8 and bytes->string/utf-8 as appropriate.

> (stomp-connect "dev.rabbitmq.com"

#:login "guest"

#:passcode "guest"

#:virtual-host "/")

Any headers given in headers are included in the CONNECT frame.

The optional request-versions argument should be a list of strings indicating the STOMP protocol versions to ask for when negotiating with the server. If omitted, it defaults to asking for STOMP version 1.1. The server will choose a protocol variant that it supports from this list. You can check the version that the server chose using stomp-session-version. If the server supports none of the requested versions, it should fall back to STOMP version 1.0. To force the use of STOMP version 1.0, pass in '() as request-versions.

The following example demonstrates the use of a receipt request with a SEND operation:

> (call-with-receipt session

(lambda (receipt)

(stomp-send session

"/queue/a"

(string->bytes/utf-8 "some message body")

#:headers `((receipt ,receipt)))))

Note that this is a low-level way of sending commands to the server: better to use stomp-send, stomp-subscribe, stomp-ack-message etc.

If you are working with a STOMP server such as ActiveMQ that interprets the presence or absence of a content-length header as an indicator of the content type, you can use the use-content-length parameter to override the default behaviour. Setting it to 'default causes the header to be generated whenever body is non-empty. Setting it to 'always causes it to always be generated, and setting it to 'never causes it to never be generated. You should omit use-content-length unless you are certain you need to work with a broken server.

If subscription-id is 'any, the next available MESSAGE frame is returned, no matter the contents of its subscription header.

If subscription-id is #f, the next available MESSAGE frame that has no subscription header at all is returned.

If subscription-id is a string, then the returned MESSAGE frame’s subscription header will match it exactly.

If subscription-id is a set of strings, then the next MESSAGE frame with a subscription header that is a member of the set is returned.

This is the procedure you will want to use to actually publish messages to the STOMP server.

In some cases, you may need to use the use-content-length parameter. See stomp-send-command for details. You should omit this parameter unless you are certain that you need to set it.

• 'auto — The server will not expect any ACK frames in response to MESSAGEs it sends. This is the default.

• 'client — The server will expect ACK frames, and will interpret an acknowledgement of message ID m to mean that message and all preceding messages.

• 'client-individual — The server will expect ACK frames, but will interpret each such frame as acknowledging only the message ID mentioned within it.

Proceeds without waiting for a reply. To wait for a reply, supply a receipt header; see call-with-receipt.

If subscription-id is #f, then no subscription identifier will be associated with this subscription, and you may have difficulty telling which subscription any resulting MESSAGE frames relate to. You may also have difficulty cancelling such subscriptions since you will have to use an (ambiguous) destination, instead of an unambiguous subscription identifier.

If subscription-id is #f, then destination must be non-#f, and the cancellation request will operate using the possibly-ambiguous notion of destination instead of the unambiguous notion of a subscription identifier. Servers may differ in how they treat this situation. It is always safe to use a unique per-subscription identifier when subscribing and unsubscribing.

Use this procedure or stomp-ack-message to acknowledge messages received via a call to stomp-subscribe where ack-mode was either 'client or 'client-individual.

Start, commit, or abort a transaction, respectively. Transaction names are managed by the client. See the STOMP specification for BEGIN, COMMIT and ABORT for more information on how transaction names are used.

The procedure call-with-stomp-transaction abstracts away from some of the detail of managing transactions for you.