=head1 NAME AnyEvent::STOMP::Client - An event-based non-blocking STOMP 1.2 client based on AnyEvent and Object::Event. =head1 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; =head1 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)). =head1 METHODS =head2 $client = new $host, $port, $connect_headers, $tls_context Create an instance of C. =over =item C<$host> String, optional, defaults to C. The host, where a STOMP-compatible message broker is running. =item C<$port> Integer, optional, defaults to C<61613>. The TCP port we connect to. I.e. the port where the message broker instance is listening. =item C<$connect_headers> Hash, optional, empty by default. May be used to add arbitrary headers to the STOMP C frame. STOMP login headers would, for example, be supplied using this parameter. =item C<$tls_context> Hash, optional, undef by default. May be used to supply a SSL/TLS context directly to C. See L for documentation. =back =head3 Example C<< my $client = AnyEvent::STOMP::Client->new( '127.0.0.1', 61614, {'login' => 'guest', 'passcode' => 'guest', 'virtual-host' => 'foo'} ); >> =head2 $client = connect Connect to the specified STOMP message broker. Croaks if you already established a connection. =head2 $client->disconnect Sends a C STOMP frame to the message broker (if we are still connected). Croaks, if you are trying to disconnect without actually being connected. =over =item C<$ungraceful> Boolean, defaults to 0. If the ungraceful option is set, then simply a C 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 C frame. =back =head2 bool $client->is_connected Check whether we are still connected to the broker. May only be accurate if STOMP heart-beats are used. =head2 $subscription_id = $client->subscribe $destination, $ack_mode, $additional_headers Subscribe to a destination by sending a C STOMP frame to the message broker. Returns the subscription identifier. =over =item C<$destination> String, mandatory. The destination to which we want to subscribe to. =item C<$ack_mode> C | C | C, optional, defaults to C. See the STOMP documentation for further information on acknowledgement modes. =item C<$additional_headers> Used to pass arbitrary headers to the C STOMP frame. Broker specific flow control parameters for example is what would want to supply here. =back =head2 $client->unsubscribe $destination, $additional_headers Unsubscribe from a destination by sending an C STOMP frame to the message broker. =over =item C<$destination> String, mandatory. The destination from which we want to unsubscribe. =item C<$additional_headers> Used to pass arbitrary headers to the C STOMP frame. =back =head2 $client->send $destination, $headers, $body Send a STOMP C frame to the message broker. =over =item C<$destination> String, mandatory. The destination to which to send the message to. =item C<$header> Hash, optional, empty by default. Arbitrary headers included in the C frame. See the STOMP documentation for supported headers. =item C<$body> String, optional, empty by default. The body of the message, according to the content-type specified in the header. =back =head2 $client->ack $ack_id, $transaction_id Send an C frame to acknowledge a received message. =over =item C<$ack_id> String, mandatory. Has to match the C header of the message that is to be acknowledged. =item C<$transaction_id> String, optional. A transaction identifier, if the C is part of a transaction. =back =head2 $client->nack $ack_id, $transaction_id Send an C frame to NOT acknowledge a received message. =over =item C<$ack_id> String, mandatory. Has to match the C header of the message that is to be nacked. =item C<$transaction_id> String, optional. A transaction identifier, if the C is part of a transaction. =back =head2 $client->begin_transaction $transaction_id, $additional_headers Begin a STOMP transaction. =over =item C<$transaction_id> String, mandatory. A unique identifier for the transaction. =item C<$additional_headers> Hash, optional, empty by default. Used to pass arbitrary headers to the STOMP frame. =back =head2 $client->commit_transaction $transaction_id, $additional_headers Commit a STOMP transaction. =over =item C<$transaction_id> String, mandatory. A unique identifier for the transaction. =item C<$additional_headers> Hash, optional, empty by default. Used to pass arbitrary headers to the STOMP frame. =back =head2 $client->abort_transaction $transaction_id, $additional_headers Abort a STOMP transaction. =over =item C<$transaction_id> String, mandatory. A unique identifier for the transaction. =item C<$additional_headers> Hash, optional, empty by default. Used to pass arbitrary headers to the STOMP frame. =back =head2 $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. =head2 Callbacks In order for the C to be useful, callback subroutines can be registered for the following events: =head3 $guard = $client->on_connected $callback Invoked when a CONNECTED frame is received. Parameters passed to the callback: C<$self>, C<$header_hashref>. =head3 $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 C 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: C<$self>, C<$host>, C<$port>. =head3 $guard = $client->on_connection_lost $callback Invoked when either the C callback specified in the C constructor is called, or when no more heartbeats arrive from the server. Parameters passed to the callback: C<$self>, C<$host>, C<$port>, C<$error_message>. =head3 $guard = $client->on_connect_error $callback Invoked when the C callback specified in the C constructor is called. Parameters passed to the callback: C<$self>, C<$host>, C<$port>. =head3 $guard = $client->on_send_frame $callback Invoked when a STOMP frame is sent. Parameters passed to the callback: C<$self>, C<$frame> (the sent frame as string). =head3 $guard = $client->on_send $callback Invoked when a STOMP SEND command is sent. Parameters passed to the callback: C<$self>, C<$frame> (the sent frame as string). =head3 $guard = $client->on_ack $callback Invoked when a STOMP ACK command is sent. Parameters passed to the callback: C<$self>, C<$frame> (the sent frame as string). =head3 $guard = $client->on_nack $callback Invoked when a STOMP NACK command is sent. Parameters passed to the callback: C<$self>, C<$frame> (the sent frame as string). =head3 $guard = $client->on_read_frame $callback Invoked when a STOMP frame is received (irrespective of the STOMP command). Parameters passed to the callback: C<$self>, C<$command>, C<$header_hashref>, C<$body> (may be C, if the frame is not specified to contain a body). =head3 $guard = $client->on_message $callback $destination Invoked when a MESSAGE frame is received. Optionally, a C<$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: C<$self>, C<$header_hashref>, C<$body>. =head3 $guard = $client->on_receipt $callback Invoked when a RECEIPT frame is received. Parameters passed to the callback: C<$self>, C<$header_hashref>. =head3 $guard = $client->on_error $callback Invoked when an ERROR frame is received. Parameters passed to the callback: C<$self>, C<$host>, C<$port>, C<$error_message>. =head3 $guard = $client->on_subscribed $callback Invoked after having successfully subscribed to a destination. Works behind the scenes like the C described above. Parameters passed to the callback: C<$self>, C<$destination>. =head3 $guard = $client->on_unsubscribed $callback Invoked after having successfully unsubscribed to a destination. Works behind the scenes like the C described above. Parameters passed to the callback: C<$self>, C<$destination>. =head3 $client->unregister_callback $guard To unregister a previously registered callback. =over =item C<$guard> The return value of one of the above on_ subroutines, identifying the registered callback. =back =head1 BUGS / LIMITATIONS =over =item Currently only the most recent version of STOMP, i.e. 1.2, is supported. =back =head1 SEE ALSO L, L, L, L, L =head1 AUTHOR Raphael Seebacher, Eraphael@seebachers.chE =head1 COPYRIGHT AND LICENSE Copyright (C) 2013 by L. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.