NAME

Tibco::Rv::Cm::Transport - Tibco Certified Messaging transport object

SYNOPSIS

   my ( $cmt ) = $rv->createCmTransport( cmName => 'cmlisten',
      ledgerName => 'cmlisten.ldg', requestOld => Tibco::Rv::TRUE );
   $rv->createCmListener( subject => 'FOO', transport => $cmt, callback => sub
   {
      my ( $msg ) = shift;
      print "Message from ", $msg->CMSender, '/', $msg->CMSequence, ": $msg\n";
   } );

DESCRIPTION

A Tibco::Rv::Cm::Transport object represents a connection to a Rendezvous daemon, which routes messages to other Tibco programs. With Certified Messaging, each message is guaranteed to be delievered exactly once and in sequence.

CONSTRUCTOR

$transport = new Tibco::Rv::Cm::Transport( %args )

   %args:
      transport => $transport,
      service => $service,
      network => $network,
      daemon => $daemon,
      cmName => $cmName,
      requestOld => $requestOld,
      ledgerName => $ledgerName,
      syncLedger => $syncLedger,
      relayAgent => $relayAgent,
      defaultCMTimeLimit => $defaulCMTimeLimit,
      publisherInactivityDiscardInterval => $publisherInactivityDiscardInterval

Creates a Tibco::Rv::Cm::Transport. If not specified, requestOld defaults to Tibco::Rv::FALSE, syncLedger defaults to Tibco::Rv::FALSE, defaultCMTimeLimit defaults to 0 (no time limit), and publisherInactivityDiscardInterval defaults to 0 (no time limit). If transport is not specified, a new transport is created using the given service/network/daemon parameters (which default as usual).

cmName is the certified messaging correspondent name. If cmName is undef, then a unique, non-reusable name is generated for the duration of the object. If cmName is specified, it becomes a persistent correspondent identified by this name.

If requestOld is Tibco::Rv::TRUE, then unacknowledged messages sent to this persistent correspondent name will be re-requested from senders. If it is Tibco::Rv::TRUE, senders will not retain unacknowledged messages in their ledger files.

If ledgerName is specified, then this transport will use a file-based ledger by that name. Otherwise, a process-based ledger will be used.

If syncLedger is Tibco::Rv::TRUE, operations that update the ledger file will not return until changes are written out to the storage medium. If it is Tibco::Rv::TRUE, the operating system writes changes to the disk asynchronously.

If relayAgent is specified, the transport will connect to the given rvrad.

defaultCMTimeLimit is the number of seconds a certified sender is guaranteed to retain the message. It may be overridden for each message. A time limit of 0 represents no time limit.

See your TIB/Rendezvous documentation for more information about publisherInactivityDiscardInterval, which was introduced in tibrv 7.3. If Tibco::Rv was built against a version prior to 7.3, then the constructor will die with a Tibco::Rv::VERSION_MISMATCH Status message if you attempt to set publisherInactivityDiscardInterval to anything other than 0.

METHODS

$service = $transport->service

Returns the service setting $transport is connected to.

$network = $transport->network

Returns the network setting $transport is connected to.

$daemon = $transport->daemon

Returns the daemon setting $transport is connected to.

$description = $transport->description

Returns the description of $transport.

$transport->description( $description )

Sets the description of $transport. Description identifies this transport to TIB/Rendezvous components. It is displayed in the browser administration interface.

$batchMode = $transport->batchMode

Returns the batchMode of $transport. If Tibco::Rv was built against an Rv 6.x version, this method will always return Tibco::Rv::Transport::DEFAULT_BATCH.

$transport->batchMode( $batchMode )

Sets the batchMode of $transport. See the Constants section for a discussion of the available batchModes. If Tibco::Rv was built against an Rv 6.x version, this method will die with a Tibco::Rv::VERSION_MISMATCH Status message.

$name = $transport->name

Returns the correspondent name of $transport.

$ledgerName = $transport->ledgerName

Returns the ledger name of $transport, or undef if not using a file-based ledger.

$relayAgent = $transport->relayAgent

Returns the relay agent of $transport, or undef if not using a a relay agent.

$requestOld = $transport->requestOld

Returns the requestOld flag of $transport.

$syncLedger = $transport->syncLedger

Returns the syncLedger flag of $transport.

$transport = $transport->transport

Returns the underlying Tibco::Rv::Transport object used by $transport, a Tibco::Rv::Cm::Transport object.

$defaultCMTimeLimit = $transport->defaultCMTimeLimit

Returns the default certified messaging time limit $transport will use for messages that otherwise do not have a time limit assigned.

$transport->defaultCMTimeLimit( $defaultCMTimeLimit )

Set the default certified messaging time limit for $transport.

$interval = $transport->publisherInactivityDiscardInterval

Returns the publisherInactivityDiscardInterval of $transport. See your TIB/Rendezvous documentation for more information about publisherInactivityDiscardInterval, which was introduced in tibrv 7.3. If Tibco::Rv was built against a version prior to 7.3, this method will always return 0.

$transport->publisherInactivityDiscardInterval( $interval )

See your TIB/Rendezvous documentation for more information about publisherInactivityDiscardInterval, which was introduced in tibrv 7.3. If Tibco::Rv was built against a version prior to 7.3, this method will die with a Tibco::Rv::VERSION_MISMATCH Status message.

$transport->send( $msg )

Sends $msg via $transport on the subject specified by $msg's sendSubject.

$reply = $transport->sendRequest( $request, $timeout )

Sends $request (a Tibco::Rv::Cm::Msg) and waits for a reply message. This method blocks while waiting for a reply. $timeout specifies how long it should wait for a reply. Using Tibco::Rv::WAIT_FOREVER causes this method to wait indefinately for a reply.

If $timeout is not specified (or undef), then this method uses Tibco::Rv::WAIT_FOREVER.

If $timeout is something other than Tibco::Rv::WAIT_FOREVER and that timeout is reached before receiving a reply, then this method returns undef.

$transport->sendReply( $reply, $request )

Sends $reply (a Tibco::Rv::Cm::Msg) in response to the $request message. This method extracts the replySubject from $request, and uses it to send $reply.

$inbox = $transport->createInbox

Returns a subject that is unique within $transport's domain. If $transport is the Intra-Process Transport, then $inbox is unique within this process; otherwise, $inbox is unique across all processes within the local router domain.

Use createInbox to set up a subject for point-to-point communications. That is, messages sent to this subject will go to a single destination.

createInbox should be used in conjunction with sendReply and sendRequest to enable point-to-point communication, as follows:

On the replying end, create a listener that listens to some subject. In the callback of that listener, create a routine that sends a reply to incoming requests via the sendReply method.

On the requesting end, create an inbox subject using createInbox. Then, create your request message, and use that message's replySubject method to set the reply subject to be the inbox subject you just created. Send that request message via the transport's sendRequest method. The sendRequest method internally creates a listener and waits for the replying end to send a reply.

$status = $transport->addListener( $cmName, $subject )

Pre-register an anticipated listener named $cmName on the given subject, so that certified messages sent on that subject will be stored in $transport's ledger. Returns Tibco::Rv::NOT_PERMITTED if $cmName has been disallowed by a call to disallowListener, otherwise returns Tibco::Rv::OK.

$status = $transport->removeListener( $cmName, $subject )

Unregister the listener listening on $subject at correspondent named $cmName, and free associated storage in $transport's ledger. Returns Tibco::Rv::INVALID_SUBJECT if the correspondent named $cmName does not receive certified delivery on$subject, otherwise returns Tibco::Rv::OK.

$transport->disallowListener( $cmName )

Cancel certified delivery to all listeners at correspondent named $cmName, and refuse subsequent certified delivery requests from that correspondent.

$transport->allowListener( $cmName )

Allow future certified delivery requests from correspondent named $cmName, cancelling the effect of a previous call to disallowListener.

$transport->removeSendState( $subject )

Remove send state for given subject in $transport's ledger file.

$status = $transport->sync

Synchronize $transport's ledger file to its storage medium. Returns Tibco::Rv::INVALID_ARG if $transport does not have a ledger file, otherwise returns Tibco::Rv::OK.

$transport->reviewLedger( $subject, $callback )

Subject information from $transport's ledger file matching the given subject are passed to the given callback, which must be a subroutine reference (sub { ... }). The callback is called once for each subject that matches $subject (i.e., wildcards are allowed).

The subject information is passed to the callback as a Tibco::Rv::Msg. See your TIB/Rendezvous documentation for more information on the fields in the Msg and what they mean.

$status = $transport->connectToRelayAgent

Connect $transport to its designated relay agent. Returns Tibco::Rv::INVALID_ARG if $transport does not have a designated relay agent (otherwise returns Tibco::Rv::OK).

$status = disconnectFromRelayAgent

Disconnects $transport from its designated relay agent. Returns Tibco::Rv::INVALID_ARG if $transport does not have a designated relay agent (otherwise returns Tibco::Rv::OK).

$transport->DESTROY

Destroy this connection to a TIB/Rendezvous daemon after flushing all outbound messages. Events created with this transport are invalidated. Called automatically when $transport goes out of scope. Calling DESTROY more than once has no effect.

SEE ALSO

Tibco::Rv::Transport

Tibco::Rv::Cm::Msg

AUTHOR

Paul Sturm <sturm@branewave.com>