TibrvCmTransport()

Method

Declaration

TibrvCmTransport(
    TibrvRvdTransport  transport)
  throws TibrvException
TibrvCmTransport(
    TibrvRvdTransport  transport,
    java.lang.String   cmName,
    boolean            requestOld)
  throws TibrvException
TibrvCmTransport(
    TibrvRvdTransport  transport,
    java.lang.String   cmName,
    boolean            requestOld,
    java.lang.String   ledgerName,
    boolean            syncLedger)
  throws TibrvException
TibrvCmTransport(
    TibrvRvdTransport  transport,
    java.lang.String   cmName,
    boolean            requestOld,
    java.lang.String   ledgerName,
    boolean            syncLedger)
  throws TibrvException

Purpose

Create a transport for certified delivery.

Remarks

The new certified delivery transport must employ a valid transport for network communications.

The certified delivery transport remains valid until the program explicitly destroys it.


Parameter	Description
`transport`	The new TibrvCmTransport employs this transport object for network communications. This object must be a TibrvRvdTransport. Destroying the TibrvCmTransport does not affect this TibrvRvdTransport object.
`cmName`	Bind this reusable name to the new TibrvCmTransport, so the TibrvCmTransport represents a persistent correspondent with this name. If non-`null`, the name must conform to the syntax rules for Rendezvous subject names. It cannot begin with reserved tokens. It cannot be a non-reusable name generated by another call to TibrvCmTransport(). It cannot be the empty string. If omitted or `null`, then TibrvCmTransport() generates a unique, non-reusable name for the duration of the transport. For more information, see Name.
`requestOld`	This parameter indicates whether a persistent correspondent requires delivery of messages sent to a previous certified delivery transport with the same name, for which delivery was not confirmed. Its value affects the behavior of other CM sending transports. If this parameter is `true` and `cmName` is non-`null`, then the new TibrvCmTransport requires certified senders to retain unacknowledged messages sent to this persistent correspondent. When the new TibrvCmTransport begins listening to the appropriate subjects, the senders can complete delivery. (It is an error to supply `true` when `cmName` is `null`.) If this parameter is `false` (or omitted), then the new TibrvCmTransport does not require certified senders to retain unacknowledged messages. Certified senders may delete those messages from their ledgers.
`ledgerName`	If this argument is non-`null`, then the new TibrvCmTransport uses a file-based ledger. The argument must represent a valid file name. Actual locations corresponding to relative file names conform to operating system conventions. We strongly discourage using the empty string as a ledger file name. If omitted or `null`, then the new TibrvCmTransport uses a process-based ledger. For more information, see Ledger File.
`syncLedger`	If this argument is `true`, then operations that update the ledger file do not return until the changes are written to the storage medium. If this argument is `false` (or omitted), the operating system writes changes to the storage medium asynchronously.

Method Forms

With only a transport, create a transient correspondent, with a unique, non-reusable name. (Supplying null as the cmName has the same effect.)

All other parameters are optional, with default values when omitted.

Name

If cmName is null, then TibrvCmTransport() generates a unique, non-reusable name for the new certified delivery transport.

If cmName is non-null, then the new transport binds that name. A correspondent can persist beyond transport destruction only when it has both a reusable name and a file-based ledger.

For more information about the use of reusable names, see CM Correspondent Name in TIBCO Rendezvous Concepts, and Persistent Correspondents in TIBCO Rendezvous Concepts. For details of reusable name syntax, see Reusable Names in TIBCO Rendezvous Concepts.

Ledger File

Every certified delivery transport stores the state of its certified communications in a ledger.

If ledgerFile is null, then the new transport stores its ledger exclusively in process-based storage. When you destroy the transport or the process terminates, all information in the ledger is lost.

If ledgerFile specifies a valid file name, then the new transport uses that file for ledger storage. If the transport is destroyed or the process terminates with incomplete certified communications, the ledger file records that state. When a new transport binds the same reusable name, it reads the ledger file and continues certified communications from the state stored in the file.

Even though a transport uses a ledger file, it may sometimes replicate parts of the ledger in process-based storage for efficiency; however, programmers cannot rely on this replication.

The syncLedger parameter determines whether writing to the ledger file is a synchronous operation:

• To specify synchronous writing, supply true. Each time Rendezvous software writes a ledger item, the call does not return until the data is safely stored in the storage medium.

• To specify asynchronous writing (the default), supply false. Certified delivery calls may return before the data is safely stored in the storage medium, which results in greater speed at the cost of certainty. The ledger file might not accurately reflect program state in cases of hardware or operating system kernel failure (but it is accurate in cases of sudden program failure). Despite this small risk, we strongly recommend this option for maximum performance.

A program that uses an asynchronous ledger file can explicitly synchronize it by calling TibrvCmTransport.syncLedger().

Destroying a transport with a file-based ledger always leaves the ledger file intact; it neither erases nor removes a ledger file.

The ledger file must reside on the same host computer as the program that uses it.