NAME

AnyEvent::STOMP::Client - An event-based non-blocking STOMP 1.2 client based on AnyEvent and Object::Event.

SYNOPSIS

use AnyEvent::STOMP::Client;

my $stomp_client = new AnyEvent::STOMP::Client()

$stomp_client->connect();

$stomp_client->on_connected(
    sub {
        my $self = shift;

        $self->subscribe('/queue/test-destination');

        $self->send(
            '/queue/test-destination',
            {'content-type' => 'text/plain',},
            "Hello World!"
        );
    }
);

$stomp_client->on_message(
    sub {
        my ($self, $header, $body) = @_;
        print "$body\n";
    }
);

AnyEvent->condvar->recv;

DESCRIPTION

AnyEvent::STOMP::Client provides a STOMP (Simple Text Oriented Messaging Protocol) client. Thanks to AnyEvent, AnyEvent::STOMP::Client is completely non-blocking, by making extensive use of the AnyEvent::Handle and timers (and, under the hood, AnyEvent::Socket). Building on Object::Event, AnyEvent::STOMP::Client implements various events (e.g. the MESSAGE event, when a STOMP MESSAGE frame is received) and offers callbacks for these (e.g. on_message($callback)).

METHODS

$client = new $host, $port, $connect_headers, $tls_context

Create an instance of AnyEvent::STOMP::Client.

$host

String, optional, defaults to localhost. The host, where a STOMP-compatible message broker is running.

$port

Integer, optional, defaults to 61613. The TCP port we connect to. I.e. the port where the message broker instance is listening.

$connect_headers

Hash, optional, empty by default. May be used to add arbitrary headers to the STOMP CONNECT frame. STOMP login headers would, for example, be supplied using this parameter.

$tls_context

Hash, optional, undef by default. May be used to supply a SSL/TLS context directly to AnyEvent::Handle. See AnyEvent::TLS for documentation.

Example

my $client = AnyEvent::STOMP::Client->new( '127.0.0.1', 61614, {'login' => 'guest', 'passcode' => 'guest', 'virtual-host' => 'foo'} );

$client = connect

Connect to the specified STOMP message broker. Croaks if you already established a connection.

$client->disconnect

Sends a DISCONNECT STOMP frame to the message broker (if we are still connected). Croaks, if you are trying to disconnect without actually being connected.

$ungraceful

Boolean, defaults to 0. If the ungraceful option is set, then simply a DISCONNECT STOMP frame is sent and the connection state is considered to be disconnected without awaiting any response from the server. If, however, the option is not set, then a receipt is asked for and the connection is only considered to be no longer established upon receiving a receipt for the DISCONNECT frame.

bool $client->is_connected

Check whether we are still connected to the broker. May only be accurate if STOMP heart-beats are used.

$subscription_id = $client->subscribe $destination, $ack_mode, $additional_headers

Subscribe to a destination by sending a SUBSCRIBE STOMP frame to the message broker. Returns the subscription identifier.

$destination

String, mandatory. The destination to which we want to subscribe to.

$ack_mode

auto | client | client-individual, optional, defaults to auto. See the STOMP documentation for further information on acknowledgement modes.

$additional_headers

Used to pass arbitrary headers to the SUBSCRIBE STOMP frame. Broker specific flow control parameters for example is what would want to supply here.

$client->unsubscribe $destination, $additional_headers

Unsubscribe from a destination by sending an UNSUBSCRIBE STOMP frame to the message broker.

$destination

String, mandatory. The destination from which we want to unsubscribe.

$additional_headers

Used to pass arbitrary headers to the UNSUBSCRIBE STOMP frame.

$client->send $destination, $headers, $body

Send a STOMP SEND frame to the message broker.

$destination

String, mandatory. The destination to which to send the message to.

$header

Hash, optional, empty by default. Arbitrary headers included in the SEND frame. See the STOMP documentation for supported headers.

$body

String, optional, empty by default. The body of the message, according to the content-type specified in the header.

$client->ack $ack_id, $transaction_id

Send an ACK frame to acknowledge a received message.

$ack_id

String, mandatory. Has to match the ack header of the message that is to be acknowledged.

$transaction_id

String, optional. A transaction identifier, if the ACK is part of a transaction.

$client->nack $ack_id, $transaction_id

Send an NACK frame to NOT acknowledge a received message.

$ack_id

String, mandatory. Has to match the ack header of the message that is to be nacked.

$transaction_id

String, optional. A transaction identifier, if the NACK is part of a transaction.

$client->begin_transaction $transaction_id, $additional_headers

Begin a STOMP transaction.

$transaction_id

String, mandatory. A unique identifier for the transaction.

$additional_headers

Hash, optional, empty by default. Used to pass arbitrary headers to the STOMP frame.

$client->commit_transaction $transaction_id, $additional_headers

Commit a STOMP transaction.

$transaction_id

String, mandatory. A unique identifier for the transaction.

$additional_headers

Hash, optional, empty by default. Used to pass arbitrary headers to the STOMP frame.

$client->abort_transaction $transaction_id, $additional_headers

Abort a STOMP transaction.

$transaction_id

String, mandatory. A unique identifier for the transaction.

$additional_headers

Hash, optional, empty by default. Used to pass arbitrary headers to the STOMP frame.

$client->destroy

Disconnects and cleans up all callbacks. To be called when the client object is not used any more and should be cleaned up.

Callbacks

In order for the AnyEvent::STOMP::Client to be useful, callback subroutines can be registered for the following events:

$guard = $client->on_connected $callback

Invoked when a CONNECTED frame is received. Parameters passed to the callback: $self, $header_hashref.

$guard = $client->on_disconnected $callback

Invoked after having successfully disconnected from a broker. I.e. when a callback is registered for this event and the disconnect subroutine is called, then a receipt header is included in the DISCONNECT frame and the disconnected event is fired upon receiving the receipt for the DISCONNECT frame. Parameters passed to the callback: $self, $host, $port.

$guard = $client->on_connection_lost $callback

Invoked when either the on_error callback specified in the AnyEvent::Handle constructor is called, or when no more heartbeats arrive from the server. Parameters passed to the callback: $self, $host, $port, $error_message.

$guard = $client->on_connect_error $callback

Invoked when the on_connect_error callback specified in the AnyEvent::Handle constructor is called. Parameters passed to the callback: $self, $host, $port.

$guard = $client->on_send_frame $callback

Invoked when a STOMP frame is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).

$guard = $client->on_send $callback

Invoked when a STOMP SEND command is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).

$guard = $client->on_ack $callback

Invoked when a STOMP ACK command is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).

$guard = $client->on_nack $callback

Invoked when a STOMP NACK command is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).

$guard = $client->on_read_frame $callback

Invoked when a STOMP frame is received (irrespective of the STOMP command). Parameters passed to the callback: $self, $command, $header_hashref, $body (may be undef, if the frame is not specified to contain a body).

$guard = $client->on_message $callback $destination

Invoked when a MESSAGE frame is received. Optionally, a $destination parameter may be specified, resulting in the callback only being invoked, when a MESSAGE is received from that specific destination. Parameters passed to the callback: $self, $header_hashref, $body.

$guard = $client->on_receipt $callback

Invoked when a RECEIPT frame is received. Parameters passed to the callback: $self, $header_hashref.

$guard = $client->on_error $callback

Invoked when an ERROR frame is received. Parameters passed to the callback: $self, $host, $port, $error_message.

$guard = $client->on_subscribed $callback

Invoked after having successfully subscribed to a destination. Works behind the scenes like the on_disconnected described above. Parameters passed to the callback: $self, $destination.

$guard = $client->on_unsubscribed $callback

Invoked after having successfully unsubscribed to a destination. Works behind the scenes like the on_disconnected described above. Parameters passed to the callback: $self, $destination.

$client->unregister_callback $guard

To unregister a previously registered callback.

$guard

The return value of one of the above on_<xyz> subroutines, identifying the registered callback.

BUGS / LIMITATIONS

• Currently only the most recent version of STOMP, i.e. 1.2, is supported.

SEE ALSO

AnyEvent, AnyEvent::Handle, AnyEvent::TLS, Object::Event, STOMP 1.2 Documentation

AUTHOR

Raphael Seebacher, <raphael@seebachers.ch>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Open Systems AG. All rights reserved.

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