Raphael Seebacher

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.

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.

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.

$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, $header_hashref, $body.

$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.