WebLogic Server 6.1 API Reference

weblogic.wtc.jatmi
Interface Conversation

All Known Implementing Classes:

TPServiceInformation

public interface Conversation

This interface is considered to be of BETA quality. It has not gone through the complete regression cycle that the other interfaces have been put through. Official BEA support channels will not support this interface in this release of WTC. Support for this API is through the WTC Beta newsgroup. This interface should not be used in production applications. BEA makes no claim that the methods in this interface will remain unchanged in future versions of the WTC product. Hence, any clients that use this interface may need to be recompiled if they use this interface.

This interface represents a conversation, either from the initiator or receiver perspective. It is modelled on the conversational interface of the Tuxedo product.

Author:

BEA Systems, Inc.
Copyright © 2001 BEA Systems, Inc. All Rights Reserved.

Method Summary

void	tpdiscon() This API is considered to be of BETA quality.
Reply	tprecv(int flags) This API is considered to be of BETA quality.
void	tpsend(TypedBuffer data, int flags) This API is considered to be of BETA quality.

Method Detail

tpsend

public void tpsend(TypedBuffer data,
                   int flags)
            throws TPException

This API is considered to be of BETA quality. It has not gone through the complete regression cycle that the other API in this interface has been put through. Official BEA support channels will not support this interface in this release of WTC. Support for this API is through the WTC Beta newsgroup. This interface should not be used in production applications. BEA makes no claim that this method will remain unchanged in future versions of the WTC product. Hence, any clients that use this interface may need to be recompiled if they use this interface.

tpsend is used to send data across an open connection to another program The caller must have control of the connection.

Parameters:

data - The data to send on this conversation

flags -

• TPRECVONLY This flag signifies that after the callers data is sent the caller gives up control of the connection (that is, the caller can not issue any more tpsend() calls). When the receiver on the other end of the conversation receives the data sent by tpsend(), it will get a TPReplyException with the data and with tperrno set to TPEEVENT and revent set to TPEV_SENDONLY.
• TPNOBLOCK The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).
• TPNOTIME This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.

Throws:

TPException - Upon failure, tpsend() returns a TPException exception to indicate the error condition. tperrno in TPException will be set to one of the following values:

• TPEINVAL Invalid arguments were given (for example, svc is null, or flags are invalid).
• TPETIME A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified. If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set).
• TPEEVENT An event occurred. data is not sent when this error occurs. The event type is returned in revent and can be one of the following
  • TPEV_DISCONIMM Received by the subordinate of a conversation, this event indicates that the originator of the conversation has issued an immediate disconnect on the connection via tpdiscon(), or it has completed a service or committed or rolled back a transaction while the converation was still connected. This event is also returned to the originator or subordinate when a connection is broken due to a communications error (for example, a server, machine or network failure)
  • TPEV_SVCERR Received by the originator of a conversation, this event indicates that the subordinate of the conversation has completed the service without having control of the conversation. In addition the service was issued in a manner different from that described for TPEV_SVCFAIL below.
  • TPEV_SVCFAIL Received by the originator of a conversation, this event indicates that the subordinate of the conversation has completed its service request without having control of the conversation. Or the service was completed with the status of TPFAIL or TPEXIT and data was set to null.
• TPEBLOCK A blocking condition exists and TPNOBLOCK was specified.
• TPEPROTO tpsend() was called improperly.
• TPESYSTEM A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• TPEOS An operating system error has occurred.

tprecv

public Reply tprecv(int flags)
             throws TPException,
                    TPReplyException

This API is considered to be of BETA quality. It has not gone through the complete regression cycle that the other API in this interface has been put through. Official BEA support channels will not support this interface in this release of WTC. Support for this API is through the WTC Beta newsgroup. This interface should not be used in production applications. BEA makes no claim that this method will remain unchanged in future versions of the WTC product. Hence, any clients that use this interface may need to be recompiled if they use this interface.

Used to receive data sent across an open connection from another program.

Parameters:

flags - The following is a list of valid flags:

• TPNOBLOCK tprecv() does not wait for the reply to arrive. If the reply is available, then tprecv() gets the reply and returns. When this flag is not specified and a reply is not available, the caller blocks until the reply arrives or a timeout occurs (either transaction or blocking timeout).
• TPNOTIME This flag signifies that the caller is willing to block indefinitely for its reply and wants to be immune to blocking timeouts. Transaction timeouts may still occur.

Returns:

Upon success of tprecv() a Reply object that contains the reply data from tpsend()

Throws:

TPException - Upon failure, tprecv() throws TPException() to indicate the error condition. tperrno in TPException will be set to one of the following values:

• TPEINVAL Invalid arguments were given (for example, cd or flags are invalid).
• TPEOTYPE The type and sub-type of the reply are not known to the caller. If the reply was to be received on behalf of the caller's current transaction, then the transaction is marked abort-only since the reply is discarded.
• TPETIME A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified. If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply and is not sent on behalf of the caller's transaction (that is, tpacall() with TPNOTRAN, TPNOBLOCK and TPNOREPLY set).
• TPEEVENT An event occurred. Further information is available in revent, which may contain
  • TPEV_DISCONIMM Received by the subordinate of a conversation, this event indicates that the originator of the conversation has either issued an immediate disconnect on the connection via tpdiscon(), or it has completed the service or committed or aborted the transaction with the connectio still open. This event is also returned to the originator or subordinate when a connection is broken due to a communications error (for example, a server, machine or network failure). Because this is an immediate disconnect notification (that is abortive rather than orderly) data in transit may be lost. If the two programs were participating in the same transaction, the the transaction is marked abort-only. This conversation object is no longer valid.
  • TPEV_SVCERR Received by the originator of a conversation, this event indicates that the subordinate of a conversation has compelted the service. The service encountered an error that precluded the service from returning successfully. For example, bad arguments may have been passed into tpreturn() or tpreturn may have been called with open connections to other subordinates. Due to the nature of this event any application defined data or return code are not available. The connection has been torn down and this conversation object is no longer valid. If this event is part of the recipient's transaction, then the transaction is marked abort-only.
• TPEBLOCK A blocking condition exists and TPNOBLOCK was specified.
• TPEPROTO tpgetrply() was called improperly.
• TPESYSTEM A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• TPEOS An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may possibly be returned.

TPReplyException - If there was an event with data. tperrno will be set to TPEEVENT and revent can be one of the following

• TPEV_SENDONLY The program on the other end of the connection has relinquished control of the connection. The recipient of this event is allowed to send data but cannot receive any data until it relinquishes control
• TPEV_SVCFAIL Received by the originator of the conversation, this event indicates that the subordinate service on the other end of the conversation has finished unsuccessfully as defined by the application (that is, it called tpreturn with TPFAIL or TPEXIT). If the subordinate service was in control of the conversation when tpreturn was called then it can pass an application defined return value and a TypedBuffer back to the originator of the conversation. As part of ending the service routine, the server has torn down the connection. This conversation object is no longer valid. If this event occurred as part of the recipients transaction, then the transaction is marked abort-only.
• TPEV_SVCSUCC Received by the originator of a conversation, this event indicates that the subordinate service on the other end of the conversation has finished successfully as defined by the application (that is, it called tpreturn with TPSUCCESS). As part of ending the service routine, the server has torn down the conversation. This conversation object is no longer valid. If the recipient is in transaction mode, then it can either commit (if it is the initiator) or abort the transaction causing the work done by the server (if also in transaction mode) to either commit or abort.

tpdiscon

public void tpdiscon()
              throws TPException

This API is considered to be of BETA quality. It has not gone through the complete regression cycle that the other API in this interface has been put through. Official BEA support channels will not support this interface in this release of WTC. Support for this API is through the WTC Beta newsgroup. This interface should not be used in production applications. BEA makes no claim that this method will remain unchanged in future versions of the WTC product. Hence, any clients that use this interface may need to be recompiled if they use this interface.

immediatly tears down the connection and generates a TPEV_DISONIMM event on the other end of the connection. tpdiscon can only be called by the initiator of the conversation. tpdiscon cannot be called within a conversational service on the object passed into the service. Rather, a conversational service must end the service normally to signify that it has completed its part of the conversation. Similarly, even though a program communicating with a conversational service can issue tpdiscon(), the preferred way is to let the service tear down the connection; doing so ensures correct results. tpdiscon() causes the connection to be torn down immediatly (that is, abortive rather than orderly). Any data that has not yet reached its destination may be lost. tpdiscon() can be issued even when the program on the other end of the connection is participating in the caller's transaction. In this case, the transaction must be aborted. Also, the caller does not need to have control of the connection when tpdiscon() is called.

Throws:

TPException - Upon failure, tpdiscon() throws TPException() to indicate the error condition. tperrno in TPException will be set to one of the following values:

• TPETIME A timeout occurred. This object is no longer valid.
• TPEPROTO tpdison() was called in an improper context
• TPESYSTEM A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• TPEOS An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may possibly be returned.