/ 
XAS-0.05
River stage one • 6 direct dependents • 6 total dependents
/ XAS::Lib::Stomp::POE::Client

NAME

XAS::Lib::Stomp::POE::Client - A STOMP client for the POE Environment

SYNOPSIS

This module is a class used to create clients that need to access a message server that communicates with the STOMP protocol. Your program could look as follows:

package Client;

use POE;
use XAS::Class
  version => '1.0',
  base    => 'XAS::Lib::Stomp::POE::Client',
;

sub handle_connection {
   my ($kernel, $self) = @_[KERNEL, OBJECT];

   my $nframe = $self->stomp->connect(
       -login    => 'testing',
       -passcode => 'testing'
   ); 

   $kernel->yield('send_data', $nframe);

}

sub handle_connected {
   my ($kernel, $self, $frame) = @_[KERNEL, OBJECT, ARG0];

   my $nframe = $self->stomp->subscribe(
       -queue => $self->queue,
       -ack   => 'client'
   );

   $kernel->yield('send_data', $nframe);

}

sub handle_message {
   my ($kernel, $self, $frame) = @_[KERNEL, OBJECT, ARG0];

   my $nframe = $self->stomp->ack(
      -message_id => $frame->header->message_id
   );

   $kernel->yield('send_data', $nframe);

}

package main;

use POE;
use strict;

Client->new(
   -alias => 'testing',
   -queue => '/queue/testing',
);

$poe_kernel->run();

exit 0;

DESCRIPTION

This module handles the nitty-gritty details of setting up the communications channel to a message queue server. You will need to sub-class this module with your own for it to be useful.

An attempt to maintain that channel will be made when/if that server should happen to disappear off the network. There is nothing more unpleasent then having to go around to dozens of servers and restarting processes.

When messages are received, specific events are generated. Those events are based on the message type. If you are interested in those events you should override the default behaviour for those events. The default behaviour is to do nothing.

METHODS

new

This method initializes the class and starts a session to handle the communications channel. It takes the following parameters:

-alias

The session alias, defaults to 'stomp-client'.

-server

The servers hostname, defaults to 'localhost'.

-port

The servers port number, defaults to '61613'.

-target

The STOMP protocol version that is targeted. Defaults to '1.0'.

-retry_count

Wither to attempt reconnections after they run out. Defaults to true.

-enable_keepalive

For those pesky firewalls, defaults to false

send_data

You use this event to send Stomp frames to the server.

Example
$kernel->yield('send_data', $frame);

handle_connection

This event is signaled and the corresponding method is called upon initial connection to the message server. For the most part you should send a "CONNECT" frame to the server.

Example

   sub handle_connection {
       my ($kernel, $self) = @_[KERNEL,$OBJECT];

      my $nframe = $self->stomp->connect(
          -login => 'testing',
          -passcode => 'testing'
      );

      $kernel->yield('send_data', $nframe);

   }

handled_connected

This event and corresponing method is called when a "CONNECT" frame is received from the server. This means the server will allow you to start generating/processing frames.

Example

   sub handle_connected {
       my ($kernel, $self, $frame) = @_[KERNEL,$OBJECT,ARG0];

       my $nframe = $self->stomp->subscribe(
           -queue => $self->queue,
           -ack => 'client'
       );

       $kernel->yield('send_data', $nframe);

   }

This example shows you how to subscribe to a particular queue. The queue name was passed as a parameter to new().

handle_message

This event and corresponding method is used to process "MESSAGE" frames.

Example

   sub handle_message {
       my ($kernel, $self, $frame) = @_[KERNEL,OBJECT,ARG0];

       my $nframe = $self->stomp->ack(
           -message_id => $frame->header->message_id
       );

       $kernel->yield('send_data', $nframe);

   }

This example really doesn't do much other then "ack" the messages that are received.

handle_receipt

This event and corresponding method is used to process "RECEIPT" frames.

Example

   sub handle_receipt {
       my ($kernel, $self, $frame) = @_[KERNEL,$OBJECT,ARG0];

       my $receipt = $frame->header->receipt;

   }

This example really doesn't do much, and you really don't need to worry about receipts unless you ask for one when you send a frame to the server. So this method could be safely left with the default.

handle_error

This event and corresponding method is used to process "ERROR" frames.

Example

   sub handle_error {
       my ($kernel, $self, $frame) = @_[KERNEL,$OBJECT,ARG0];

   }

This example really doesn't do much. Error handling is pretty much what the process needs to do when something unexpected happens.

gather_data

This event and corresponding method is used to "gather data". How that is done is up to your program. But usually a "send_data" event is generated.

Example

   sub gather_data {
       my ($kernel, $self) = @_[KERNEL,$OBJECT];

       # doing something here

       $kernel->yield('send_data', $frame);

   }

connection_down

This event and corresponding method is a hook to allow you to be notified if the connection to the server is currently down. By default it does nothing. But it would be usefull to notify "gather_data" to temporaily stop doing whatever it is currently doing.

Example

   sub connection_down {
       my ($kernel, $self) = @_[KERNEL,OBJECT];

       # do something here

   }

connection_up

This event and corresponding method is a hook to allow you to be notified when the connection to the server up. By default it does nothing. But it would be usefull to notify "gather_data" to start doing whatever it supposed to do.

Example

   sub connection_up {
      my ($kernel, $self) = @_[KERNEL,OBJECT];

      # do something here

   }

cleanup

This method is a hook and should be overidden to do "shutdown" stuff. By default it sends a "DISCONNECT" message to the message queue server.

Example

   sub handle_shutdown {
       my ($self, $kernel, $session) = @_;

       # do something here

   }

reload

This method is a hook and should be overidden to do "reload" stuff. By default it executes POE's sig_handled() method.

Example

   sub reload {
       my ($self, $kernel, $session) = @_;

       $kernel->sig_handled();

   }

ACCESSORS

stomp

This returns an object to the interal XAS::Lib::Stomp::Utils object. This is very useful for creating STOMP frames.

Example

   $frame = $self->stomp->connect(
        -login    => 'testing',
        -passcode => 'testing'
   );

   $kernel->yield('send_data', $frame);

SEE ALSO

XAS
For details on the protocol see L<http://stomp.github.io/>.

AUTHOR

Kevin L. Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Kevin L. Esteb

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.