Version 16 of Stomp

Updated 2013-05-19 21:25:18 by EF

STOMP stands for the Simple (or Streaming) Text Oriented Messaging Protocol. STOMP provides an interoperable wire format so that STOMP clients can communicate with any STOMP message broker to provide easy and widespread messaging interoperability among many languages, platforms and brokers.

STOMP is loosely modeled after the HTTP protocol, where "messages" will typically start with an uppercase command (like GET in HTTP), followed by a number of headers (format is similar) and possibly followed by a body. Messages are ended by ^@, i.e. the zero character, aka ASCII 0, '\0'. STOMP advocates utf-8 on the wire and provides mechanisms that keep the connection alive, if necessary, thus making sure routers do not close connections. The complete specification is rather short and specifically targets scripting languages.

As I (EF) needed to understand STOMP in a better way, and despite there was already an implementation available at [L1 ], I decided to start coding it from scratch again. The resulting library is in the half-bakery [L2 ]. For the time being, it only provides a STOMP client implementation. The implementation is almost complete, it is only missing support for transactions. However, I intend to code it all the way, resulting in a simple "broker" implementation, an implementation that would allow any Tcl application to implement a STOMP server.

My implementation differentiates itself from the other in the following ways:

  • It is coded in pure Tcl, without any object layer. It should even be running on oldish implementations of the language, i.e. 8.4 (not tested though).
  • It implements the heart-beating facilities as of the specification.
  • It handles automated reconnections, but also gentle disconnection, as of the specification.
  • It provides introspection facilities to be notified of the changes in connection state.
  • It supports receipts for messages.
  • Apart from a high-level interface to subscriptions, it also provides a lower-level interface to PUB/SUB mechanisms. This allows to provide full support for the different types of acknowledgements specified.
  • It provides an interface to low-level messaging on the wire.

The current implementation has had little testing, initial tests against the Apache Apollo broker have shown proper behaviour. Please send any positive or negative feedback to me on the usual channels.

The following script highlights some of the capabilities of the library.

package require stomp

proc received { cid rid } {
    puts "Server has received message, id: $rid"
}
 
proc incoming { msg } {
    puts "Incoming message: [::stomp::message::getCommand $msg]"
}

# Connect to broker (following is default admin user for Apollo)
set s [::stomp::connect -user admin -password password]

# Subscribe to a queue at the server and arrange to receive
# messages for that queue in the procedure called "incoming"
# We wait before the subscription because connecting to a server
# implies a handshake mechanism. Instead, we could use the
# introspection mechanisms provided by the -liveness option to
# ::stomp::connect
after 1000 ::stomp::subscribe $s /queue/a \
    -handler incoming

# Send a message to the same queue, meaning we'll receive it
# in the "incoming" procedure. Also make sure we'll receive
# a receipt for the message in the procedure "received"
after 2000 ::stomp::send $s /queue/a -body "Hello world" -receipt received

# Disconnect after a while, you might want to force disconnection from
# the web UI at the server to see what happens in the mean time.
after 60000 ::stomp::disconnect $s

# Live for ever..
vwait forever

APN Very much interested in this, the server side as well. So happens I was looking for a simple message broker implementation in script and your post showed up. Serendipity!

EF You are welcome, and please try it as it's really in its early days... :) As long as you're not too impatient, I hope to be able to finish up some initial version of the server within the next few weeks. It needs some refactoring, moving out most of the actual code to a ::stomp::client namespace so I can start having common procedures in ::stomp and start with a ::stomp::server.

APN Any thought of putting it in a public repository ? The half-bakery is not the most convenient for keeping track of changes.

APN Tried it (took an hour to set up Apollo thanks to spaces in the path to the JRE). Looks pretty good. Stopped and restarted Apollo and life went on without a hitch. Didn't see how to get the data of received message so directly accessed the ::stomp::message::msg_* array. Also binary data did not seem to get through, probably I have to explicitly set the content-length header. Looks like a great start.

For anyone else interested in trying this out, here is a summary of steps to set up Apache Apollo on Windows:

  • Download and extract the Apache Apollo distribution
  • Download the Java server JRE (just the desktop JRE is not enough). There does not seem to be a 32-bit version of this. You probably have to download the entire JDK if you are on 32-bit Windows. The download is a compressed tar file though the extension is just gz. Rename it to .tar.gz so 7-zip will correctly handle it.
  • Extract to (for example) c:\src\jdk1.7.0_21
  • Then type the following commands in the command shell (assuming c:\src\stomp-test is the directory that will hold your Apollo config)
set JAVA_HOME=c:\src\jdk1.7.0_21 (Note no quotes around the path even if it has spaces else batch files will fail)
cd c:\src\stomp-test
C:\bin\x86\apache-apollo-1.6\bin\apollo create mybroker
mybroker\bin\apollo-broker.cmd run
  • A mybroker subdirectory is created
  • Ctrl-C to exit/stop
  • There is also an option to run as a service
  • To connect to the admin interface, connect to http://127.0.0.1:61680/

EF It'll probably end up in my efr-tools , or if suitable in the tcllib (dreaming?). There are a number of procedures to access the messages ::stomp::message::get*. This is loosely based on the API of the HTTP package where you have a set of procedures to access the most usual bits and pieces, but where you can access the array directly. There is some code to set the content-length automatically if you haven't set it, to be frank... there might be bugs there!