AnyEvent::STOMP::Client - An event-based non-blocking STOMP 1.2 client based on AnyEvent and Object::Event.
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;
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)).
Create an instance of AnyEvent::STOMP::Client.
AnyEvent::STOMP::Client
$host
String, optional, defaults to localhost. The host, where a STOMP-compatible message broker is running.
localhost
$port
Integer, optional, defaults to 61613. The TCP port we connect to. I.e. the port where the message broker instance is listening.
61613
$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.
CONNECT
$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.
AnyEvent::Handle
my $client = AnyEvent::STOMP::Client->new( '127.0.0.1', 61614, {'login' => 'guest', 'passcode' => 'guest', 'virtual-host' => 'foo'} );
Connect to the specified STOMP message broker. Croaks if you already established a connection.
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.
DISCONNECT
$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.
Check whether we are still connected to the broker. May only be accurate if STOMP heart-beats are used.
Subscribe to a destination by sending a SUBSCRIBE STOMP frame to the message broker. Returns the subscription identifier.
SUBSCRIBE
$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.
auto
client
client-individual
$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.
Unsubscribe from a destination by sending an UNSUBSCRIBE STOMP frame to the message broker.
UNSUBSCRIBE
String, mandatory. The destination from which we want to unsubscribe.
Used to pass arbitrary headers to the UNSUBSCRIBE STOMP frame.
Send a STOMP SEND frame to the message broker.
SEND
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.
Send an ACK frame to acknowledge a received message.
ACK
$ack_id
String, mandatory. Has to match the ack header of the message that is to be acknowledged.
ack
$transaction_id
String, optional. A transaction identifier, if the ACK is part of a transaction.
Send an NACK frame to NOT acknowledge a received message.
NACK
String, mandatory. Has to match the ack header of the message that is to be nacked.
String, optional. A transaction identifier, if the NACK is part of a transaction.
Begin a STOMP transaction.
String, mandatory. A unique identifier for the transaction.
Hash, optional, empty by default. Used to pass arbitrary headers to the STOMP frame.
Commit a STOMP transaction.
Abort a STOMP transaction.
Disconnects and cleans up all callbacks. To be called when the client object is not used any more and should be cleaned up.
In order for the AnyEvent::STOMP::Client to be useful, callback subroutines can be registered for the following events:
Invoked when a CONNECTED frame is received. Parameters passed to the callback: $self, $header_hashref.
$self
$header_hashref
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.
disconnect
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.
on_error
$error_message
Invoked when the on_connect_error callback specified in the AnyEvent::Handle constructor is called. Parameters passed to the callback: $self, $host, $port.
on_connect_error
Invoked when a STOMP frame is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).
$frame
Invoked when a STOMP SEND command is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).
Invoked when a STOMP ACK command is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).
Invoked when a STOMP NACK command is sent. Parameters passed to the callback: $self, $frame (the sent frame as string).
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).
$command
undef
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.
Invoked when a RECEIPT frame is received. Parameters passed to the callback: $self, $header_hashref.
Invoked when an ERROR frame is received. Parameters passed to the callback: $self, $host, $port, $error_message.
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.
on_disconnected
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.
To unregister a previously registered callback.
$guard
The return value of one of the above on_<xyz> subroutines, identifying the registered callback.
Currently only the most recent version of STOMP, i.e. 1.2, is supported.
AnyEvent, AnyEvent::Handle, AnyEvent::TLS, Object::Event, STOMP 1.2 Documentation
Raphael Seebacher, <raphael@seebachers.ch>
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.
To install AnyEvent::STOMP::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm AnyEvent::STOMP::Client
CPAN shell
perl -MCPAN -e shell install AnyEvent::STOMP::Client
For more information on module installation, please visit the detailed CPAN module installation guide.