NAME

Tibco::Rv::Listener - Tibco Listener event object

SYNOPSIS

my ( $listener ) =
   $rv->createListener( subject => 'ABC', callback => sub
{
   my ( $msg ) = @_;
   print "Listener got a message: $msg\n";
} );

my ( $msg ) = $rv->createMessage( field => 'value' );
$listener->onEvent( $msg );

DESCRIPTION

A Tibco::Rv::Listener monitors a subject for incoming messages and passes those messages along to a callback. It is a subclass of Tibco::Rv::Event, so Event methods are available to Listeners (documentation on Event methods are reproduced here for convenience).

CONSTRUCTOR

$listener = new Tibco::Rv::Listener( %args )

%args:
   queue => $queue,
   transport => $transport,
   subject => $subject,
   callback => sub { ... }

Creates a Tibco::Rv::Listener. If not specified, queue defaults to the Default Queue, transport defaults to the Intra-Process Transport, subject defaults to the empty string, and callback defaults to:

sub { print "Listener received: @_\n" }

A program registers interest in $subject by creating a Listener. Messages coming in on $subject via $transport are placed on the $queue. When $queue dispatches such an event, it triggers the given callback.

METHODS

$transport = $listener->transport

Returns the transport via which Listener events are arriving.

$subject = $listener->subject

Returns the subject this Listener is listening on.

$queue = $listener->queue

Returns the queue on which this Listener's events will be dispatched.

$callback = $listener->callback

Returns the callback code reference.

$listener->onEvent( $msg )

Trigger an event directly by passing $msg to the Listener. The $msg will be processed as if it was triggered via the event queue.

$listener->DESTROY

Cancels interest in this event. Called automatically when $listener goes out of scope. Calling DESTROY more than once has no effect.

OVERRIDING EVENT CALLBACK

As an alternative to passing in a callback function to the constructor, there is another way to handle events. You can subclass Tibco::Rv::Listener and override the onEvent method, as follows:

package MyListener;
use base qw/ Tibco::Rv::Listener /;

sub new
{
   my ( $proto, %args ) = @_;
   my ( $self ) = $proto->SUPER::new( %args );
   # your initialization code
   return $self;
}

sub onEvent
{
   my ( $self, $msg ) = @_;
   # process $msg here
   # $self->queue, $self->transport, $self->subject are available
}

# any other implementation code for your class

1;

The Tibco::Rv::Event onEvent method simply passes the $msg on to the callback, so overriding onEvent allows you to process the $msg however you want, and you can just not use the callback.

The advantages of this method of handling events are: it is more object-oriented; you have access to the transport, queue, and subject via the $self accessor methods; and, you can have more elaborate processing of incoming messages without having to shove it all into one callback.

You can use your subclassed Listener as follows:

use Tibco::Rv;
use MyListener;

my ( $rv ) = new Tibco::Rv;
my ( $transport ) = new Tibco::Rv::Transport;
my ( $myListener ) =
   new MyListener( transport => $transport, subject => 'ABC' );
$rv->start;

AUTHOR

Paul Sturm <sturm@branewave.com>