weblogic.wtc.jatmi
Interface Conversation

All Known Implementing Classes:

TPServiceInformation

public interface Conversation

This interface represents a conversation between a client and server over an open conection. The process that opens a connection and starts a conversation is the originator of the conversation. The process with control of the connection is the initiator; the process without control is called the subordinate. The connection remains active until an event occurs to terminate it. This interface is modeled on the conversational interface of the Tuxedo product.

tpsend

void tpsend(TypedBuffer data,
            int flags)
            throws TPException

Sends data across an open connection from an initiator to a subordinate Tuxedo application.

Parameters:

data - Pointer to the data buffer; null specifies no data sent.

flags - The following is a list of valid flags:

• TPRECVONLY: Specifies after this initiator's data is sent, the initiator gives up control of the connection. The initiator becomes subordinate and only receives data. When the subordinate receives data, tperrno is set to TPEEVENT and revent is set to TPEV_SENDONLY.
• TPNOBLOCK: Specifies this request is not sent if a blocking condition exists. For example, a blocking condition exists if the internal buffers into which this message is transferred are full. If TPNOBLOCK is not specified and a blocking condition exists, the initiator blocks until the condition subsides, a transaction timeout occurs, or a blocking timeout occurs.
• TPNOTIME: Specifies this initiator blocks indefinitely and is immune from blocking timeouts but remains subject to transaction timeouts.

Throws:

TPException - Returns a TPException exception indicating the error condition. tperrno is set to one of the following values:

• TPEINVAL: Invalid arguments given. For example: svc is null or flags are invalid.
• TPEPROTO: Called using an improper context.
• TPESYSTEM: A Tuxedo system error occurred. The exact nature of the error is written to a log file.

tprecv

Reply tprecv(int flags)
             throws TPException,
                    TPReplyException

Receives data sent across an open connection from a Tuxedo application. Since the initiator of this conversation is a Tuxedo Remote Domain, Tuxedo Domains Protocol specifies a result of remote service execution is returned as an event.

Parameters:

flags - The following is a list of valid flags:

• TPNOBLOCK: Specifies that tprecv does not wait for a reply to arrive. If a reply is available, tprecv gets the reply and returns. If this flag is not specified and a reply is not available, tprecv waits for one of the following to occur: a reply, a transaction timeout, or a blocking timeout.
• TPNOTIME: Specifies tprecv waits indefinitely for a reply. tprecv is immune from blocking timeouts but is subject to transaction timeouts.
• A flag value of 0 specifies this initiator blocks until the condition subsides or a timeout occurs.

Returns:

A Reply object that contains the reply data from tpsend. A successful termination of a conversation is determined with a catch of a TPReplyException where the revent is set to TPEV_SVCSUCC.

Throws:

TPException - Returns TPException indicating the error condition. tperrno is set to one of the following values:

• TPEBLOCK: A blocking condition exists and TPNOBLOCK is specified.
• TPEINVAL: Invalid arguments given. For example: cd or flags are invalid.
• TPEPROTO: Called using an improper context.
• TPESYSTEM: A Tuxedo system error occurred. The exact nature of the error is written to a log file.

TPReplyException - Returns a TPReplyException indicating an event condition. tperrno is set to TPEEVENT and revent is one of the following:

• TPEV_DISCONIMM: Received by the subordinate of a conversation indicating originator of the conversation: issued an immediate disconnect using tpdiscon; completed the service; committed or aborted the transaction with the connection still open. This event is also returned to the initiator or subordinate when a connection is broken due to a communications error. For example: a server, machine or network failure. This event signifies an abortive disconnect and indicates that data in transit may be lost. If two programs were participating in the same transaction, the transaction is marked abort-only and the conversation object is no longer valid.
• TPEV_SENDONLY: Received by the subordinate of a conversation indicating the initiator of the conversation relinquished control of the connection. The recipient becomes the initiator to send data but cannot receive any data until it relinquishes control.
• TPEV_SVCERR: Received by the initiator of a conversation indicating the subordinate completed a service that did not return sucessfully. For example: bad arguments passed into tpreturn or tpreturn was called with open connections to other subordinates. The connection is disconnected in an orderly manner and this conversation object is no longer valid. Application defined data or return codes are not available. If part of the recipient's transaction, the transaction is marked abort-only.
• TPEV_SVCFAIL: Received by the initiator of the conversation indicating the subordinate service finished unsuccessfully as defined by the application. An Application defined return value and a TypedBuffer are returned to the initiator. For example: tpreturn called with TPFAIL or TPEXIT. The connection is disconnected in an orderly manner and this conversation object is no longer valid. If part of the recipient's transaction, the transaction is marked abort-only.
• TPEV_SVCSUCC: Received by the initiator of a conversation indicating the subordinate service finished successfully as defined by the application - tpreturn called with TPSUCCESS. The connection is disconnected in an orderly manner and this conversation object is no longer valid. If the recipient initiated a transaction, it can commit the transaction or abort the transaction causing work done by the server in the same transaction to commit or abort.

tpdiscon

void tpdiscon()
              throws TPException

Executes a disorderly disconnect by immediately tearing down the connection and generating a TPEV_DISCONIMM event on the other end of the connection. A tpdiscon is called by the initiator of the conversation. Any data that has not yet reached its destination may be lost. If the conversation is part of a transaction, the transaction must be rolled back.

Whenever possible allow: Tuxedo conversational services to end a conversation with a tpreturn; WebLogic Server conversational services to end a conversation with call to return. Letting the service tear down the connection ensures an orderly disconnect.

Throws:

TPException - Returns a TPException indicating an error condition. tperrno is set to one of the following values:

• TPEPROTO Called using an improper context.
• TPESYSTEM A Tuxedo system error occurred. The exact nature of the error is written to a log file.