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
.
$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.
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.
$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 theDISCONNECT
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.
$destination
-
String, mandatory. The destination to which we want to subscribe to.
$ack_mode
-
auto
|client
|client-individual
, optional, defaults toauto
. 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.
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.
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.
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.
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.
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.
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.
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.
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
.
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
.
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
.
Invoked when the on_connect_error
callback specified in the AnyEvent::Handle
constructor is called. Parameters passed to the callback: $self
, $host
, $port
.
Invoked when a STOMP frame is sent. Parameters passed to the callback: $self
, $frame
(the sent frame as string).
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).
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
, $header_hashref
, $body
.
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
.
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, <[email protected]>
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.