/ 
POE-Component-Client-Stomp-0.12
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::Client::Stomp

NAME

POE::Component::Client::Stomp - A Perl extension 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 base qw(POE::Component::Client::Stomp);

use strict;
use warnings;

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({destination => $self->config('Queue'), 
                                         ack => 'client'});
   $kernel->yield('send_data' => $nframe);

}

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

   my $message_id = $frame->headers->{'message-id'};
   my $nframe = $self->stomp->ack({'message-id' => $message_id});
   $kernel->yield('send_data' => $nframe);

}

package main;

use POE;
use strict;

   Client->spawn(
       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 usefull.

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

spawn

This method initializes the class and starts a session to handle the communications channel. The only parameters that having meaning are:

    Alias           - The session alias, defaults to 'stomp-client'
RemoteAddress   - The servers hostname, defaults to 'localhost'
RemotePort      - The servers port, defaults to '61613'
RetryReconnect  - Wither to attempt reconnections after they run out
EnableKeepAlive - For those pesky firewalls, defaults to false

All other parameters are stored within an internal config.

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({destination => $self->config('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 spawn() so it is available in the $self->{CONFIG} hash.

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 $message_id = $frame->headers->{'message-id'};
    my $nframe = $self->stomp->ack({'message-id' => $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->headers->{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

}
log

This method is used internally to send a log message to stdout. It can be overridden to hook into your perferred logging module. This module currently uses the following levels internally: 'warn', 'error', 'debug'

Example
sub log {
    my ($self, $kernel, $level, @args) = @_;

    if ($level eq 'error') {

        $kernel->post('logger' => error => @args);

    } elsif ($level eq 'warn') {

        $kernel->post('logger' => warn => @args);

   }

}
handle_shutdown

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

}
handle_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 handle_reload {
   my ($self, $kernel, $session) = @_;

   $kernel->sig_handled();

}

ACCESSORS

stomp

This returns an object to the interal POE::Component::Client::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);
config

This accessor is used to return items from the internal config. The config is loaded from the parameters that were used when spawn() was called.

Example
$logger = $self->config('Logger');

SEE ALSO

Net::Stomp::Frame
POE::Filter::Stomp
POE::Component::MessageQueue
POE::Compoment::Client::Stomp::Utils;

For information on the Stomp protocol: http://stomp.codehaus.org/Protocol

AUTHOR

Kevin L. Esteb, <kesteb@wsipc.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007 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.