NAME

POE::Component::Client::Stomp - Perl extension for the POE Environment

SYNOPSIS

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

package myclient;

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('handle_send' => $nframe);

}

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

   my $nframe = $self->{stomp}->subscribe({destination => $self->{CONFIG}->{Queue}, ack => 'client'});
   $kernel->yield('handle_send' => $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('handle_send' => $nframe);

}

package main;

use POE;
use strict;

    myclient->spawn(
       Alias => 'testing',
       Queue => '/queue/testing',
   );

   $poe_kernel->run();

   exit 0;

DESCRIPTION

This module is an object wrapper. It handles the nitty-gritty details of setting up the communications channel to a message queue server. It will attempt to maintain that channel when/if that server should happen to disappear off the network. There is nothing more unpleasent then having to go around to 30 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 object and starts a session to handle the communications channel. The only parameters that having meaning are:

Alias         - The alias for this session, defaults to 'stomp-client'
RemoteAddress - The host where the server lives, defaults to 'localhost'
RemotePort    - The port the server is listening on, defaults to '61613'

Any other passed parameters are available in the $self->{CONFIG} hash. The module POE::Component::Client::Stomp::Utils is also loaded and those methods can be reached using the $self->{stomp} variable. This module is a handy way to create STOMP frames.

handle_send

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

Example

$kernel->yield('handle_send', $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('handle_send' => $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('handle_send' => $nframe);
    
}

This example shows you how to subscribe to a particilar 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('handle_send' => $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.

SEE ALSO

Net::Stomp::Frame
POE::Filter::Stomp
POE::Component::Server::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.