STOMP is a publish/subscribe messaging protocol that allows for very lightweight communications between almost any mixture of programming languages, operating system platforms, and “message brokers”. This article goes into detail about what STOMP is, why you would want to use it, some quick-start hints to get you up and running, and a fully working example of using STOMP in your IDE Software like Delphi that extends the IDE use of plugins, such as Stomp Plugin that helps you communicate between programming languages because Delphi provides code completion and track processes.– all for free.
Table of Contents
What is STOMP?
STOMP is the Simple (or Streaming) Text Orientated Messaging Protocol. STOMP describes an agreed message protocol format so that STOMP clients can communicate and work with any STOMP message broker (the STOMP name for the server).
What is the difference between STOMP and websockets?
It’s a good question! We looked at Websockets in a previous article. Websockets are sometimes the underlying transport technology used to implement STOMP. In a sense, websockets are how the messages get passed around and STOMP is the agreed format of what is passed. STOMP doesn’t need to use websockets to work.
Is STOMP hard to use?
Like any technical subject there are a few concepts to understand but once you get comfortable with the terminology STOMP is extremely easy to use. If you write your own server applications, or ‘brokers’, any STOMP client can interact with them no matter what computer language or technology is used. The official STOMP website even states “you can use Telnet to login to any STOMP broker and interact with it”.
Behind the scenes STOMP uses headers and frames to control the back and forth of the communications. It’s modeled on HTTP but it’s more lightweight and doesn’t really have anything to do with it. The broker controls things such as an optional heartbeat system
Clients ‘SUBSCRIBE’ to a ‘topic’. The clients can then post messages to that topic. Messages sent to that channel get passed on to all clients subscribed to the same topic. Clients can be subscribed to more than one topic. Clients can also be brokers but that complicates our examples, so we’ll stick here with the idea of the client and the broker being separate entities.
STOMP subscriptions and possible uses
For example, I could write a client to subscribe to a topic called “/myapplication/errors”. Then, whenever my application encounters an error, it could send a message to the “/myapplication/errors” topic. All other clients also subscribed to that topic would receive that message and could then act on it, reply or ignore it.
Imagine that one of the clients was a status page showing a count of errors. It could show a real-time visualization of the severity, number and frequency of the errors. That status page could be a web page, a Delphi VCL application running on Windows, macOS app or a Firemonkey mobile app running on an iPhone.
The content is up to your imagination
Whilst STOMP defines how the messages get passed around the actual text content of the message is totally under your control in your code. The messages work best when they are plain text – because that’s the format underpinning the STOMP protocol – but they could just as easily be some JSON or similar text-based encoding.
First steps on how to use STOMP in your applications
RabbitMQ makes testing your Delphi STOMP programs more straight-forward.
First, it’s easiest if we install a broker to marshal the STOMP messages. The most popular message broker application is RabbitMQ. The great news is it’s open source so head on over to https://www.rabbitmq.com to download it onto your machine if you don’t already have it.
I recommend that you use Chocolatey to download and install RabbitMQ on Windows since it downloads Erlang (RabbitMQ is written in Erlang) and installs that along with several dependencies and then configures it all.
Note that you must run the installer as Administrator in order for Chocolatey to do the job of installing and configuring things properly.
You need the STOMP add-in for RabbitMQ
Downloading RabbitMQ on its own is not enough. You also need to enable RabbitMQ’s excellent STOMP broker plug-in: https://www.rabbitmq.com/stomp.html
Checking it’s all running properly
I don’t think the RabbitMQ documents make it entirely clear – but you can click on the Windows Start button and navigate to “RabbitMQ” in the list of apps. In there should be an entry to run the RabbitMQ command line. Click on that and in the terminal Window which appears type the following command: rabbitmqctl.bat status
You should be looking for no error messages and the “RabbitMQ_stomp” extension should be listed as enabled. If you don’t see that it means STOMP is not enabled and the following example of using STOMP in Delphi will not work. If that’s the case follow though RabbitMQ’s trouble-shooting. Pro tip: it’s almost certainly because you didn’t install as administrator or your firewall is blocking RabbitMQ.
Let’s download a Delphi STOMP client library
If you’re a long time Delphi user, you will not be at all surprised to find there are several STOMP client libraries – some commercial but also a few free ones.
We’re going to use the free Delphi STOMP client from Daniele Teti – found here: https://github.com/danieleteti/delphistompclient
You can clone the above repo from within the RAD Studio IDE or use one of the many the open source git clients such as Tortoise Git or my own favorite GitHub Desktop.
You should end up with a source code folder like the one shown.
Compiling and running the Delphi STOMP example
Daniele’s repository has a few examples. Let’s open the “SimpleMessaging” example.
Leave everything just as it is. Right click on the SimpleMessaging.exe name in the project manager (or hit CTRL-F9). It should build without errors.
If that’s the case, then hit F9 or select Run from the RAD Studio IDE menu.
You should see a screen like mine shown below..
It’s working!
More on the Delphi Example
If you want to pull together the things we’ve discussed about STOMP and using Delphi with STOMP then the first place to start is this section of the example program:
Notice that the subscribers – the ‘clients’ in this context – can actually subscribe to the STOMP channel before the publisher – the ‘server’ in this context – has actually published anything or joined the topic of interest to the clients.
This is an important point to note because if we refer back to our example usage scenario where our applications are publishing error messages to a “/myapplication/errors” topic it means we could have our visualization webpage already up and running and listening for messages on our custom error topic – and then show the messages as an application opens up and starts sending out updates. The reverse is true too with the server (the app) starting and the error trackers joining in the fun later.
The broker can be anywhere
Finally, the broker – which in our example is the RabbitMQ application – could be running anywhere on a PC, a corporate network or sitting on a server connected to the internet. The STOMP protocol provides for security and authentication and it’s even possible to limit access to the STOMP brokers by IP address. Powerful stuff.
How are you going to use Delphi to STOMP?