/ 
Beekeeper-0.01
River stage zero No dependents
/ Beekeeper::Bus::STOMP

NAME

Beekeeper::Bus::STOMP - A lightweight asynchronous STOMP 1.1 / 1.2 client.

VERSION

Version 0.01

SYNOPSIS

my $stomp = Beekeeper::STOMP->new(
    host  => 'localhost',
    user  => 'guest',
    pass  => 'guest',
    vhost => '/',
);

$stomp->connect( blocking => 1 );
 
$stomp->send(
    destination => '/topic/foo',
    body        => 'Hello',
);

$stomp->subscribe(
    destination => '/topic/foo',
    on_receive_msg => sub {
        my ($body, $headers) = @_;
        print "Got message: $$body";
    },
);

$stomp->disconnect( blocking => 1 );

Most methods allows to send arbitrary headers along with commands.

Except for trivial cases, error checking is delegated to the server.

The STOMP specification can be found at http://stomp.github.com/

TODO

- Send heartbeats

CONSTRUCTOR

new ( %options )

host

Hostname or IP address of the STOMP server. It also accepts an array of adresses which conforms a cluster, in which case the connection will be stablished against a randomly choosen node of the cluster.

port

Port of the STOMP server. If not specified use the STOMP default of 61613.

tls

Enable the use of TLS for STOMP connections.

vhost

Virtual host of the STOMP server to connect to.

user

Username used to authenticate against the server.

pass

Password used to authenticate against the server.

timeout

Connection timeout in fractional seconds before giving up. Default is 30 seconds. If set to zero the connection to server it retried forever.

on_connect => $cb->( \%headers )

Optional user defined callback which is called after a connection is completed.

on_error => $cb->( $errmsg )

Optional user defined callback which is called when an error condition occurs. If not specified, the deafult is to die with $errmsg. As STOMP protocol doesn't allow errors, the connection was already closed when this is called.

METHODS

connect ( %options )

Connect to the STOMP server and do handshake. On failure retries until timeout.

blocking

When set to true this method acts as a blocking call: it does not return until a connection has been established and handshake has been completed.

disconnect ( %options )

A client can disconnect from the server at anytime by closing the socket but there is no guarantee that the previously sent frames have been received by the server. This method should be called to do a graceful shutdown, where the client is assured that all previous frames have been received by the server.

blocking

When set to true this method acts as a blocking call: it does not return until disconnection has been completed.

on_success => $cb->()

Optional user defined callback which is called after disconnection is completed.

subscribe ( %headers )

Create a subscription to a given destination. When a message is received, it will be passed to given on_receive_msg callback. Example:

$stomp->subscribe(
    destination => '/topic/foo',
    on_receive_msg => sub {
        my ($body, \$headers) = @_;
        print "Got message from /topic/foo : $$body";
    },
);

Any arbitrary header may be specified, and will be passed to the server.

destination

The subscription requires the destination to which the client wants to subscribe, usually in the form of '/topic/name' or '/queue/name'.

id

An id is necessary to uniquely identify the subscription within the STOMP session. Since a single connection can have multiple open subscriptions with a server, this id allows the client and server to relate subsequent unsubscribe() or ack().

If not specified, an unique id is automatically generated.

ack

The valid values for the ack are 'auto', 'client', or 'client-individual'. If not specified the server will default to 'auto', which means that received messages doesn't require client acknowledgment.

on_success => $cb->()

Optional user defined callback which is called after subscription is completed.

on_receive_msg => $cb->( \$msg_body, \%msg_headers )

Required user defined callback which is called when a message is received.

unsubscribe ( %headers )

Cancel an existing subscription, connection will no longer receive messages from that destination. Example:

$stomp->unsubscribe( destination => '/topic/foo' );

At least one of destination or a subscription id is required.

destination

The destination of an existing subscription.

id

The id of an existing subscription.

on_success => $cb->()

Optional user defined callback which is called after unsubscription is completed.

send ( %headers )

Sends a message to a destination in the messaging system. Example:

$stomp->send(
    destination => '/topic/foo',
    body        => 'Hello!',
);

Any arbitrary header may be specified, and will be passed to the server.

destination

Mandatory header which indicates where to send the message.

body

Scalar or scalar reference containing a binary blob which conforms the body of the message. May be omitted.

on_success => $cb->()

Optional user defined callback which is called after message was received by the server.

ack ( %headers )

Used to acknowledge consumption of a message from a subscription using 'client' or 'client-individual' acknowledgment. Any messages received from such a subscription will not be considered to have been consumed until the message has been acknowledged via an ack() or nack().

Any arbitrary header may be specified, and will be passed to the server.

id

STOMP 1.2 requires this header. It must contain the value of the ack header of the message being acknowledged.

message-id

STOMP 1.1 requires this header. It must contain containing the value of the message-id header of the message being acknowledged.

subscription

STOMP 1.1 requires this header. It must contain containing the value of the subscription header of the message being acknowledged.

nack ( %headers )

nack() is the opposite of ack(). It is used to tell the server that the client did not consume the message. The server can then either send the message to a different client or discard it. The exact behavior is server specific.

flush_buffer

Send several messages into a single socket write. This is more efficient than individual send() calls because nagle's algorithm is disabled.

discard_buffer

begin ( %headers )

Used to start a transaction. Transactions in this case apply to sending and acknowledging: any messages sent or acknowledged during a transaction will be handled atomically based on the transaction.

transaction

Required transaction identifier which will be used for send, commit, abort, ack, and nack frames to bind them to a given transaction.

commit ( %headers )

Used to commit a transaction in progress.

transaction

The transaction id is required and identifies the transaction to commit.

abort ( %headers )

Used to roll back a transaction in progress.

transaction

The transaction id is required and identifies the transaction to abort.

AUTHOR

José Micó, jose.mico@gmail.com

COPYRIGHT AND LICENSE

Copyright 2015 José Micó.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language itself.

This software is distributed in the hope that it will be useful, but it is provided “as is” and without any express or implied warranties. For details, see the full text of the license in the file LICENSE.