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>