# RabbitMQ STOMP adapter

 ## Introduction

 This is a STOMP adapter plugin for use with RabbitMQ.

  - <http://stomp.codehaus.org/>

  - <http://www.rabbitmq.com/>

  - <https://dev.rabbitmq.com/wiki/StompGateway>

 You can get the code by checking it out from our repository with

     hg clone http://hg.rabbitmq.com/rabbitmq-stomp/

 Please make sure that after you have cloned the repository you update

 it to the correct tag for your RabbitMQ server version -- see below

 for details.

 Announcements regarding the adapter are periodically made on the

 RabbitMQ mailing list and on LShift's blog.

  - <http://lists.rabbitmq.com/cgi-bin/mailman/listinfo/rabbitmq-discuss>

  - <http://www.lshift.net/blog/>

  - <http://www.lshift.net/blog/category/lshift-sw/rabbitmq/>

 ### Compiling from a Mercurial checkout

 (This instructions work only for RabbitMQ 1.7.0 or newer.)

 To compile RabbitMQ STOMP adapter plugin, you will need to download

 rabbitmq-public-umbrella package:

     hg clone http://hg.rabbitmq.com/rabbitmq-public-umbrella

 Umbrella is a placeholder for various packages. You need to actually

 download and compile the dependencies. The simplest way is to run:

     cd rabbitmq-public-umbrella

     make co

     make

 This will download and compile all the rabbitmq related packages. Actually

 you don't have to compile everything, the required packages are only

 rabbitmq-codegen, rabbitmq-server and rabbitmq-stomp.

 If you want to compile a plugin for a specific release of the broker,

 you just need to update mercurial repository to a proper tag. To do

 that you can say from the umbrella directory:

     hg -R rabbitmq-codegen  up rabbitmq_v1_X_X

     hg -R rabbitmq-server   up rabbitmq_v1_X_X

     hg -R rabbitmq-stomp    up rabbitmq_v1_X_X

 ### Building plugin package

 To build a plugin package (*.ez file), run 'make package' from the

 rabbitmq-stomp directory. Package should appear in 'dist' directory.

     cd rabbitmq-stomp

     make package

     ls dist/rabbitmq_stomp.ez

 To install and activate package, please follow the instructions from

 Plugin Development Guide:

     http://www.rabbitmq.com/plugin-development.html#activating-a-plugin

 You need to install rabbit_stomp.ez package.

 ## Running the STOMP adapter

 ### Configuring the server to start the plugin automatically

 Most RabbitMQ server packages are set up to cause the server to pick

 up configuration from `/etc/rabbitmq/rabbitmq.conf`. To tell the

 server to start your plugin, first make sure it is compiled, and then

 add the following text to `/etc/rabbitmq/rabbitmq.conf`:

     SERVER_START_ARGS='-rabbit_stomp listeners [{"0.0.0.0",61613}]'

 Then restart the server with

     sudo /etc/init.d/rabbitmq-server restart

 When no configuration is specified STOMP Adapter will listen on localhost by

 default.

 ### Checking that the adapter is running

 If the adapter is running, you should be able to connect to port 61613

 using a STOMP client of your choice. In a pinch, `telnet` or netcat

 (`nc`) will do nicely:

     $ nc localhost 61613

     dummy

     dummy

     ERROR

     message:Invalid frame

     content-type:text/plain

     content-length:22

     Could not parse frame

     $ 

 That `ERROR` message indicates that the adapter is listening and

 attempting to parse STOMP frames.

 Another option is to try out the examples that come with the STOMP

 adapter -- see below.

 ### Running the adapter during development

 If you are working with the full source code for the RabbitMQ server,

 and you have the `../rabbitmq-server` directory you can simply say `make run`:

     make run

 If this is successful, you should end up with `starting

 STOMP Adapter ...done` and `broker running` in your terminal.

 ## Running tests and code coverage

 To run simplistic test suite and see the code coverage type:

     make cover

 After successfull run, you should be able to see output similar to:

     ............

     ----------------------------------------------------------------------

     Ran 12 tests in 0.300s

     [...]

     **** Code coverage ****

      54.55 rabbit_stomp

      80.88 rabbit_stomp_frame

      74.87 rabbit_stomp_server

     100.00 rabbit_stomp_sup

      75.72 'TOTAL'

 The view the code coverage, see html files in .cover:

     ls ./cover

     rabbit_stomp_frame.html

     rabbit_stomp.html

     rabbit_stomp_server.html

     rabbit_stomp_sup.html

     summary.txt

 ## Running the examples

 ### Ruby

 At this point you can try out the service - for instance, you can run

 the Ruby examples if you have Ruby and rubygems handy:

     sudo apt-get install ruby

     sudo apt-get install rubygems

     sudo gem install stomp

     ruby examples/ruby/cb-receiver.rb

 and in another window

     ruby examples/ruby/cb-sender.rb

 It will transfer 10,000 short messages, and end up displaying

     ...

     Test Message number 9998

     Test Message number 9999

     All Done!

 in the receiver-side terminal.

 ### Perl

     $ sudo cpan -i Net::Stomp

 The examples are those from the `Net::Stomp` documentation - run

 `perldoc Net::Stomp` to read the originals.

 Run the receiver before the sender to make sure the queue exists at

 the moment the send takes place. In one terminal window, start the

 receiver:

     $ perl examples/perl/rabbitmq_stomp_recv.pl

 In another terminal window, run the sender:

     $ perl examples/perl/rabbitmq_stomp_send.pl

     $ perl examples/perl/rabbitmq_stomp_send.pl "hello world"

     $ perl examples/perl/rabbitmq_stomp_send.pl QUIT

 The receiver's window should contain the received messages:

     $ perl examples/perl/rabbitmq_stomp_recv.pl 

     test message

     hello

     QUIT

     $