NAME

AnyEvent::STOMP - A lightweight event-driven STOMP client

SYNOPSIS

 use AnyEvent;
 use AnyEvent::STOMP;

 my $client = AnyEvent::STOMP->connect($host, $port, $ssl, $destination, $ack,
                                       { connect_headers },
                                       { subscribe_headers });

 $client->send($command, $headers, $body);

 # Register interest in new messages
 $client->reg_cb(MESSAGE => sub {
     my (undef, $body, $headers) = @_;
     # Do something with the frame
 });

 # Register interest in any frame received.  Use with caution.
 $client->reg_cb(frame => sub {
     my (undef, $type, $body, $headers) = @_;
     # Do something with the frame
 });

 # Start the event loop
 AnyEvent->condvar->recv;

DESCRIPTION

AnyEvent::STOMP is a lightweight event-driven STOMP client. It's intended to be run in the context of an event loop driven by AnyEvent.

Making a connection

 my $client = AnyEvent::STOMP->connect($host, $port, $ssl, $destination, $ack,
                                       { connect_headers },
                                       { subscribe_headers });

Only the first parameter (the hostname) is required. The remaining optional arguments are:

port

The port number to connect to. If not specified, defaults to 61612 (if SSL/TLS is used) or 61613 (if not).

ssl

If set to a true value, use SSL/TLS to connect.

destination

If defined, subscribe to the specified destination (queue) upon connection.

ack

Sets the behavior with respect to STOMP frame acknowledgments.

If this value is 0 or undef, no acknowledgment is required: the server will consider all sent frames to be delivered, regardless of whether the client has actually received them. (This is the default behavior according to the STOMP protocol.)

If set to auto, the client will automatically acknowledge a frame upon receipt.

If set to manual, the caller must acknowledge frames manually via the ack() method.

connect_headers

An anonymous hash of headers (key/value pairs) to send in the STOMP CONNECT frame.

subscribe_headers

An anonymous hash of headers (key/value pairs) to send in the STOMP SUBSCRIBE frame.

Sending a message

To send a message, just call send() with the body, the destination (queue) name, and (optionally) any additional headers:

 $client->send($body, $destination, $headers); # headers may be undef

Sending STOMP frames

You can also send arbitrary STOMP frames:

 $client->send_frame($command, $body, $headers); # headers may be undef

See the STOMP protocol documentation for more details on valid commands and headers.

Content Length

The content-length header is special because it is sometimes used to indicate the length of the body but also the JMS type of the message in ActiveMQ as per http://activemq.apache.org/stomp.html.

If you do not supply a content-length header, following the protocol recommendations, a content-length header will be added if the frame has a body.

If you do supply a numerical content-length header, it will be used as is. Warning: this may give unexpected results if the supplied value does not match the body length. Use only with caution!

Finally, if you supply an empty string as the content-length header, it will not be sent, even if the frame has a body. This can be used to mark a message as being a TextMessage for ActiveMQ. Here is an example of this:

 $client->send_frame($command, $body, { 'content-length' => '' } );

Events

Once you've connected, you can register interest in events, most commonly the receipt of new messages (assuming you've connected as a subscriber).

The typical use is:

 $client->reg_cb($type => $cb->($client, $body, $headers));

In most cases, $type is MESSAGE, but you can also register interest in any other type of frame (RECEIPT, ERROR, etc.). (If you register interest in CONNECTED frames, please do so with a priority of after; see Object::Event for more details.)

The client object (which can usually be ignored), body and headers (as an anonymous hash of key-value pairs) will be passed to your callback.

Other events you can register interest in are:

prepare => $cb->($client, $handle)

Will be fired after a client socket has been allocated. See on_prepare in AnyEvent::Handle for more details.

connect => $cb->($client, $handle, $host, $port, $retry->())

Will be fired when the client has successfully connected to the STOMP server. See on_connect in AnyEvent::Handle for more details.

frame => $cb->($client, $type, $body, $headers)

Will be fired whenever any frame is received.

connect_error => $cb->($client, $errmsg)

Will be fired if the attempt to connect to the STOMP server fails. See on_connect_error in AnyEvent::Handle for more details.

io_error => $cb->($client, $errmsg)

Will be fired if an I/O error occurs. See on_error in AnyEvent::Handle for more details.

Acknowledging frames

You can acknowledge a frame received via the ack() method:

  $client->ack($id, $transaction);

The transaction is optional.

Closing a session

When done with a session, you need to explicitly call the destroy() method. It will also send a DISCONNECT message on your behalf before closing. Attempting to let the object fall out-of scope is not sufficient.

  $client->destroy;

SEE ALSO

AnyEvent, AnyEvent::Handle, Object::Event, STOMP Protocol http://stomp.codehaus.org/Protocol

AUTHORS AND CONTRIBUTORS

Fulko.Hew (fulko.hew@gmail.com) is the current maintainer.

Michael S. Fischer (michael+cpan@dynamine.net) wrote the original version.

COPYRIGHT AND LICENSE

(C) 2014 SITA INC Canada, Inc. (C) 2010 Yahoo! Inc.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm AnyEvent::STOMP

perl -MCPAN -e shell
install AnyEvent::STOMP