NAME

Tibco::Rv::Cm::Listener - Tibco Certified Messaging Listener event object

SYNOPSIS

   my ( $cmt ) = $rv->createCmTransport( ... );
   my ( $listener ) =
      $rv->createCmListener( transport => $cmt, subject => 'ABC',
         callback => sub
   {
      my ( $msg ) = @_;
      print "Listener got a message: $msg, from sender: ", $msg->CMSender,
         ', sequence: ', $msg->CMSequence, "\n";
   } );

DESCRIPTION

A Tibco::Rv::Cm::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).

Certified Messaging ensures that messages will be recieved exactly once and in sequence. See your TIB/Rendevous documentation for more information.

CONSTRUCTOR

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

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

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

   sub { print "cmListener 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( $cancelAgreements )

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

If $cancelAgreements is PERSIST, certified delivery agreements are left in effect, so senders will store messages. If $cancelAgreements is CANCEL, certified delivery agreements are cancelled, causing senders to delete all messages sent to this listener.

$listener->setExplicitConfirm

By default, certified listeners automatically confirm delivery when the callback returns. By calling setExplicitConfirm, this behaviour is overridden. Instead, you must explicitly confirm delivery by calling confirmMsg.

$listener->confirmMsg( $msg )

Explicitly confirm delivery of $msg (see setExplicitConfirm).

CONSTANTS

Tibco::Rv::Cm::Listener::CANCEL => 1

Tibco::Rv::Cm::Listener::PERSIST => 0

See DESTROY for usage of these constants.

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::Cm::Listener and override the onEvent method, as follows:

   package MyListener;
   use base qw/ Tibco::Rv::Cm::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::Cm::Transport( ... );
   my ( $myListener ) =
      new MyListener( transport => $transport, subject => 'ABC' );
   $rv->start;

AUTHOR

Paul Sturm <sturm@branewave.com>