Net::STOMP::Client - STOMP object oriented client module


  # simple producer

  use Net::STOMP::Client;

  $stomp = Net::STOMP::Client->new(host => "", port => 61613);
  $stomp->connect(login => "guest", passcode => "guest");
  $stomp->send(destination => "/queue/test", body => "hello world!");

  # consumer with client side acknowledgment

  use Net::STOMP::Client;

  $stomp = Net::STOMP::Client->new(host => "", port => 61613);
  $stomp->connect(login => "guest", passcode => "guest");
  # declare a callback to be called for each received message frame
  $stomp->message_callback(sub {
      my($self, $frame) = @_;

      $self->ack(frame => $frame);
      printf("received: %s\n", $frame->body());
  # subscribe to the given queue
  $stomp->subscribe(destination => "/queue/test", ack => "client");
  # wait for a specified message frame
  $stomp->wait_for_frames(callback => sub {
      my($self, $frame) = @_;

      if ($frame->command() eq "MESSAGE") {
          # stop waiting for new frames if body is "quit"
          return(1) if $frame->body() eq "quit";
      # continue to wait for more frames
  $stomp->unsubscribe(destination => "/queue/test");


This module provides an object oriented client interface to interact with servers supporting STOMP (Streaming Text Orientated Messaging Protocol). It supports the major features of modern messaging brokers: SSL, asynchronous I/O, receipts and transactions.


The new() method can be used to create a Net::STOMP::Client object that will later be used to interact with a server. The following attributes are supported:


the STOMP version to use (string) or versions to use (reference to a list of strings); this defaults to the list of all supported versions


the Uniform Resource Identifier (URI) specifying where the STOMP service is and how to connect to it, this can be for instance tcp://msg01:6163 or something more complex such as failover:(ssl://msg01:6162,tcp://msg01:6163)


the server name or IP address


the port number of the STOMP service


the maximum time (in seconds) for various operations, see the "TIMEOUTS" section for more information


arbitrary socket options (as a hash reference) that will be passed to IO::Socket::INET->new() or IO::Socket::SSL->new()


a hash of code references that will be called on each received frame


the desired client-side heart-beat setting, see the "HEART-BEATING" section for more information


the desired server-side heart-beat setting, see the "HEART-BEATING" section for more information

Upon object creation, a TCP connection is made to the server but no data (i.e. STOMP frame) is exchanged.


When creating an object with Net::STOMP::Client->new(), if you supply some socket options (via sockopts) with a name starting with SSL_, or if you supply a URI (via uri) with a scheme containg ssl, IO::Socket::SSL will be used to create the socket instead of IO::Socket::INET and the communication with the server will then go through SSL.

Here are the most commonly used SSL socket options:


path to a directory containing several trusted certificates as separate files as well as an index of the certificates


path of your RSA private key


path of your certificate


subroutine that should return the password required to decrypt your private key

For more information, see IO::Socket::SSL.


By default, when sending STOMP frames, the module waits until the frame indeed has been sent (from the socket point of view). In case the server is stuck or unusable, the module can therefore hang.

When creating the Net::STOMP::Client object, you can pass a timeout attribute to better control how certain operations handle timeouts.

This attribute should contain a reference to hash with the following keys:


TCP-level timeout that will be given to the underlying IO::Socket::INET or IO::Socket::SSL object (default: none)


timeout used while waiting for the initial CONNECTED frame from the broker (default: 10)


timeout used while trying to send any frame (default: none)

All values are in seconds. No timeout means wait until the operation succeeds.

As a shortcut, the timeout attribute can also be a scalar. In this case, only the connect and connected operations use this value.


With a Net::STOMP::Client object, the following methods can be used to interact with the server. They match one-to-one the different commands that a client frame can hold:


connect to server


disconnect from server


subscribe to something


unsubscribe from something


send a message somewhere


acknowledge the reception of a message


acknowledge the rejection of a message (STOMP 1.1 only)


begin/start a transaction


commit a transaction


abort/rollback a transaction

All these methods can receive options that will be passed directly as frame headers. For instance:

      destination => "/queue/test",
      ack         => "client",

Some methods also support other options:


body: holds the body of the message to be sent


frame: holds the MESSAGE frame object to ACK


frame: holds the MESSAGE frame object to NACK

Finally, all methods support a timeout option that will be given to the send_frame() method called internally to send the crafted frame.


In addition to the STOMP methods, the following ones are also available:


return a new Net::STOMP::Client object


return a Net::STOMP::Client::Peer object containing information about the connected STOMP server


return the session identifier if connected or undef otherwise


return the STOMP version that has been negotiated between the client and the server or undef if the negotiation did not take place yet


return a universal pseudo-unique identifier to be used for instance in receipts and transactions


return the list of not-yet-received receipts, see the "RECEIPTS" section for more information


wait for frames coming from the server, see the next section for more information


wait for all receipts to be received, using wait_for_frames() underneath

noop([timeout => TIMEOUT])

send an empty/noop frame i.e. a single newline byte, using send_frame() underneath


Since STOMP is asynchronous (for instance, MESSAGE frames could be sent by the server at any time), Net::STOMP::Client uses callbacks to handle frames. There are in fact two levels of callbacks.

First, there are per-command callbacks that will be called each time a frame is handled (via the internal method dispatch_frame()). Net::STOMP::Client implements default callbacks that should be sufficient for all frames except MESSAGE frames, which should really be handled by the coder. These callbacks should return undef on error, something else on success.

Here is an example with a callback counting the messages received:

  $stomp->message_callback(sub {
      my($self, $frame) = @_;


Here are the methods that can be used to get or set these per-command callbacks:


These callbacks are somehow global and it is good practice not to change them during a session. If you do not need a global message callback, you can supply the dummy:

  $stomp->message_callback(sub { return(1) });

Then, the wait_for_frames() method takes an optional callback argument holding some code to be called for each received frame, after the per-command callback has been called. This can be seen as a local callback, only valid for the call to wait_for_frames(). This callback must return undef on error, false if more frames are expected or true if wait_for_frames() can now stop waiting for new frames and return.

Here are all the options that can be given to wait_for_frames():


code to be called for each received frame (see above)


time to wait before giving up, undef means wait forever, this is the default


wait only for one frame, within the given timeout

The return value of wait_for_frames() can be: undef in case of error, false if no suitable frame has been received, the received frame if there is no user callback or the user callback return value otherwise.


Net::STOMP::Client has built-in support for receipts.

Each time a frame is sent, its receipt header (if supplied) is remembered.

Each time a RECEIPT frame is received from the server, the corresponding receipt is ticked off.

The receipts() method can be used to get the list of outstanding receipts.

The wait_for_receipts() method can be used to wait for all missing receipts.

Here is sample code to send two messages with receipts and then wait for both acknowledgments to come back from the server within ten seconds:

      destination => "/queue/test1",
      body        => "message 1",
      receipt     => $stomp->uuid(),
      destination => "/queue/test2",
      body        => "message 2",
      receipt     => $stomp->uuid(),
  $stomp->wait_for_receipts(timeout => 10);
  die("Not all receipts received!\n") if $stomp->receipts();


Here is an example using transactions:

  # create a unique transaction id
  $tid = $stomp->uuid();
  # begin the transaction
  $stomp->begin(transaction => $tid);
  # send two messages as part of this transaction
      destination => "/queue/test1",
      body        => "message 1",
      transaction => $tid,
      destination => "/queue/test2",
      body        => "message 2",
      transaction => $tid,
  # commit the transaction
  $stomp->commit(transaction => $tid);


STOMP 1.1 defines how each end of a STOMP connection can check if the other end is alive. To support heart-beating, this module provides the following methods:


return the time at which data was last received, i.e. read from the network socket


return the time at which data was last sent, i.e. written to the network socket


(after having received the CONNECTED frame) return the negotiated client-side heart-beat setting


(after having received the CONNECTED frame) return the negotiated server-side heart-beat setting

beat([timeout => TIMEOUT])

send a noop frame (using the noop() method) unless the last sent time is recent enough with regard to the client heart-beat setting

For consistency with other Perl modules (for instance Time::HiRes), time is always expressed as a fractional number of seconds.

To use heart-beating, the client must specify the desired client_heart_beat and/or server_heart_beat attributes when invoking the new() method. Then, once the CONNECTED frame has been received, it can get the negotiated values with the methods above.

To prove that it is alive, the client just needs to call the beat() method.

To check if the server is alive, the client just needs to compare what is returned by the last_received() and server_heart_beat() methods.


It should be enough to use the high-level API and use, for instance, the send() method to create a MESSAGE frame and send it in one go.

If you need lower level interaction, you can manipulate frames with the Net::STOMP::Client::Frame module.

You can also use:


dispatch one received frame by calling the appropriate callback

$stomp->send_frame(FRAME, TIMEOUT)

try to send the given frame object within the given TIMEOUT, or forever if the TIMEOUT is undef


try to receive a frame within the given TIMEOUT, or forever if the TIMEOUT is undef


This module implements the versions 1.0 and 1.1 of the protocol (see as well as well known extensions for JMS, AMQP, ActiveMQ and RabbitMQ.

Note: STOMP 1.1 support is still experimental as the protocol specification is not yet finalized.

It has been successfully tested against both ActiveMQ and RabbitMQ brokers.


IO::Socket::INET, IO::Socket::SSL, Net::STOMP::Client::Error, Net::STOMP::Client::Frame, Net::STOMP::Client::Peer, Time::HiRes.


Lionel Cons

Copyright CERN 2010