WebLogic Tuxedo Connector JATMI Conversations

Note: For more information on conversational communications for BEA Tuxedo, see Writing Conversational Clients and Servers.

The following sections provide information on conversations and how to define and manage them in your applications:

 

Overview of WebLogic Tuxedo Connector Conversational Communication

WebLogic Tuxedo Connector supports BEA Tuxedo conversations as a method to exchange messages between WebLogic Server and Tuxedo applications. In this form of communication, a virtual connection is maintained between the client and the server and each side maintains information about the state of the conversation. 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.

During conversational communication, a half-duplex connection is established between the initiator and the subordinate. Control of the connection is passed between the initiator and the subordinate. The process that has control can send messages (the initiator); the process that does not have control can only receive messages (the subordinate).

 

WebLogic Tuxedo Connector Conversation Characteristics

WebLogic Tuxedo Connector JATMI conversations have the following characteristics:

  • Data is passed using TypedBuffers. The type and sub-type of the data must match one of the types and sub-types recognized by the service.
  • The logical connection between the conversational client and the conversational server remains active until it is terminated.
  • Any number of messages can be transmitted across a connection between a conversational client and the conversational server.
  • A WebLogic Tuxedo Connector conversational client initiates a request for service using tpconnect rather than a tpcall or tpacall.
  • WebLogic Tuxedo Connector conversational clients and servers use the JATMI primitives tpsend to send data and tprecv to receive data.
  • A conversational client only sends service requests to a conversational server.
  • Conversational servers are prohibited from making calls to tpforward.

 

WebLogic Tuxedo Connector JATMI Conversation Primitives

Use the following WebLogic Tuxedo Connector primitives when creating conversational clients and servers that communicate between WebLogic Server and Tuxedo:

Name

Operation

tpconnect Use to establish a connection to a Tuxedo conversational service.
tpdiscon Use to abort a connection and generate a TPEV_DISCONIMM event.
tprecv Use to receive data across an open connection from a Tuxedo application.
tpsend Use to send data across a open connection to a Tuxedo application.

 

Creating WebLogic Tuxedo Connector Conversational Clients and Servers

The following sections provide information on how to create conversational clients and servers.

 

Creating Conversational Clients

Follow the steps outlined in Developing WebLogic Tuxedo Connector Client EJBsto create WebLogic Tuxedo Connector conversational clients. The following section provide information on how to use tpconnect to open a connection and start a conversation.

 

Establishing a Connection to a Tuxedo Conversational Service

A WebLogic Tuxedo Connector conversational client must establish a connection to the Tuxedo conversational service. Use the JATMI primitive tpconnect to open a connection and start a conversation. A successful call returns an object that can be used to send and receive data for a conversation.

The following table describes tpconnect parameters:

Parameter

Description

svc Character pointer to a conversational service name. If you do not specify a svc, the call will fail and TPException is set to TPEV_DISCONIMM.
data Pointer to the data buffer. When establishing a connection, you can send data simultaneously by setting the data parameter to point to a buffer. The type and subtype of the buffer must be recognized by the service being called. You can set the value of data to NULL to specify that no data is to be sent.
flags Use flags or combinations of flags as required by your application needs. Valid flag values are:TPSENDONLY: specifies that the control is being retained by the originator. The called service is subordinate and can only receive data. Do not use in combination with TPRECVONLY.TPRECVONLY: specifies that control is being passed to the called service.The originator becomes subordinate and can only receive data. Do not use in combination with TPSENDONLY.TPNOTRAN: specifies that when svc is invoked and the originator is transaction mode, svc is not part of the originator's transaction. A call remains subject to transaction timeouts. If svc fails, the originator's transaction is unaffected.TPNOBLOCK: specifies that a request is not sent if a blocking condition exists. If TPNOBLOCK is not specified, the originator blocks until the condition subsides, a transaction timeout occurs, or a blocking timeout occurs.TPNOTIME: specifies that the originator will block indefinitely and is immune to blocking timeouts. If the originator is in transaction mode, the call is subject to transaction timeouts.

 

Example TuxedoConversationBean.java Code

The following provides a code example to use tpconnect to start a conversation:

Listing 6-1 Example Conversation Code 

.



.



.



Context ctx;



Conversation myConv;



TuxedoConnection myTux;



TuxedoConnectionFactory tcf; 



.



.



.



ctx = new InitialContext();



tcf = (TuxedoConnectionFactory) ctx.lookup ("tuxedo.services.TuxedoConnection");



myTux = tcf.getTuxedoConnection();



flags =ApplicationToMonitorInterface.TPSENDONLY;



myConv = myTux.tpconnect("CONNECT_SVC",null,flags);



.



.



.

 

Creating WebLogic Tuxedo Connector Conversational Servers

Follow the steps outlined in Developing WebLogic Tuxedo Connector Service EJBsto create WebLogic Tuxedo Connector conversational servers.

 

Sending and Receiving Messages

Once a conversational connection is established between a WebLogic Server application and a Tuxedo application, the communication between the initiator (sends message) and subordinate (receives message) is accomplished using send and receive calls. The following sections describe how WebLogic Tuxedo Connector applications use the JATMI primitives tpsend and tprecv:

 

Sending Messages

Use the JATMI primitive tpsend to send a message to a Tuxedo application.

The following table describes tpsend parameters:

Parameter

Description

data Pointer to the buffer containing the data sent with this conversation.
flags The flag can be one of the following: TPRECVONLY: specifies that after the initiator's data is sent, the initiator gives up control of the connection. The initiator becomes subordinate and can only receive data.TPNOBLOCK: specifies that the request is not sent if a blocking condition exists. If TPNOBLOCK is not specified, the originator blocks until the condition subsides, a transaction timeout occurs, or a blocking timeout occurs.TPNOTIME: specifies that an initiator is willing to block indefinitely and is immune from blocking timeouts. The call is subject to transaction timeouts.

 

Receiving Messages

Use the JATMI primitive tprecv to receive messages from a Tuxedo application.

The following table describes tprecv parameters:

Parameter

Description

flags The flag can be one of the following: 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 that tprecv waits indefinitely for a reply. tprecv is immune from blocking timeouts but is subject to transaction timeouts.A flag value of 0 specifies that the initiator blocks until the condition subsides or a timeout occurs.

 

Ending a Conversation

A conversation between WebLogic Server and Tuxedo ends when the server process successfully completes its tasks. The following sections describe how a conversation ends:

 

Tuxedo Application Originates Conversation

A WebLogic Server conversational server ends a conversation by a successful call to return. A TPEV_SVCSUCC event is sent to the Tuxedo client that originated connection to indicate that the service finished successfully. The connection is then disconnected in an orderly manner.

 

WebLogic Tuxedo Connector Application Originates Conversation

A Tuxedo conversational server ends a conversation by a successful call to tpreturn. A TPEV_SVCSUCC event is sent to the WebLogic Tuxedo Connector client that originated connection to indicate that the service finished successfully. The connection is then disconnected in an orderly manner.

 

Ending Hierarchical Conversations

The order in which an conversation ends is important to gracefully end hierarchal conversations.

Assume there are two active connections: A-B and B-C. If B is a WebLogic Tuxedo Connector application in control of both connections, a call to return has the following effect: the call fails and a TPEV_SVCERR event is posted on all open connections, and the connections are closed in a disorderly manner.

In order to terminate both connections in an orderly manner, the application must execute the following sequence:

  1. B calls tpsend with TPRECVONLY to transfer control of the B-C connection to the Tuxedo application C.
  2. C calls departure with rval set to TPSUCCESS, TPFAIL, or TPEXIT.
  3. B calls return and posts an event (TPEV_SVCSUCC or TPEV_SVCFAIL) for A.

Conversational services can make request/response calls. Therefore, in the preceding example, the calls from B to C may be executed using tpacall()or tpcall()instead of tpconnect. Conversational services are not permitted to make calls to tpforward.

 

Executing a Disorderly Disconnect

WebLogic Server conversational clients or servers execute a disorderly disconnect is through a call to tpdiscon. This is the equivalent of "pulling the plug" on a connection.

A call to tpdiscon:

  • Immediately tears down the connection and generates a TPEV_DISCONIMM at the other end of the connection. 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.
  • Can only be called by the initiator of the conversation.

 

Understanding Conversational Communication Events

WebLogic Tuxedo Connector JATMI uses five events to manage conversational communication. The following table lists the events, the functions for which they are returned, and a detailed description of each.

Event

Received by

Description

TPEV_SENDONLY Tuxedo tprecv Control of the connection has passed; this Tuxedo process can now call tpsend
JATMI tprecv Control of the connection has passed; this JATMI process can now call tpsend
TPEV_DISCONIMM Tuxedo tprecv, tpsend, tpreturn The connection has been torn down and no further communication is possible. The JATMI tpdiscon posts this event in the originator of the connection. The originator sends it to all open connections when tpreturn is called. Connections are closed in a disorderly manner and if a transaction exists, it is aborted.
JATMI tprecv, tpsend, return The connection has been torn down and no further communication is possible. The Tuxedo tpdiscon posts this event in the originator of the connection. The originator sends it to all open connections when return is called. Connections are closed in a disorderly manner and if a transaction exists, it is aborted.
TPEV_SVCERR Tuxedo tpsend or JATMI tpsend Received by the originator of the connection indicating that the subordinate program issued a tpreturn (Tuxedo) or return (JATMI) and ended without control of the connection.
Tuxedo tprecv or JATMI tprecv Received by the originator of the connection indicating that the subordinate program issued a successful tpreturn (Tuxedo) or a successful return (JATMI) without control of the connection, but an error occurred before the call completed.
TPEV_SVCSUCC Tuxedo tprecv Received by the originator of the connection, indicating that the subordinate service finished successfully; that is, return was successfully called.
JATMI tprecv Received by the originator of the connection, indicating that the subordinate service finished successfully; that is, tpreturn was called with TPSUCCESS.
TPEV_SVCFAIL Tuxedo tpsend or JATMI tpsend Received by the originator of the connection indicating that the subordinate program issued a tpreturn (Tuxedo) or return (JATMI) and ended without control of the connection. The service completed with status of TPFAIL or TPEXIT and the data is set to null.
Tuxedo tprecv or JATMI tprecv Received by the originator of the connection indicating that the subordinate program finished unsuccessfully. The service completed with status of TPFAIL or TPEXIT.

 

WebLogic Tuxedo Connector Conversation Guidelines

Use the following guidelines while in conversation mode to insure successful completion of a conversation:

  • Use the JATMI conversational primitives as defined in the WebLogic Tuxedo Connector Conversation interface and ApplicationToMonitorInterface interface.

    • Always use a flag.
    • Only use flags defined in the WebLogic Tuxedo Connector JATMI.
  • WebLogic Tuxedo Connector does not have a parameter that can be used to limit the number of simultaneous conversations to prevent overloading the WebLogic Server network.
  • If Tuxedo exceeds the maximum number of possible conversations (defined by the MAXCONV parameter), TPEV_DISCONIMM is the expected WebLogic Tuxedo Connector exception value.
  • A tprecv to an unauthorized Tuxedo service results in a TPEV_DISCONIMM exception value.
  • If a WebLogic Tuxedo Connector client is connected to a Tuxedo conversational service which does tpforward to another conversational service, TPEV_DISCONIMM is the expected WebLogic Tuxedo Connector exception value.
  • Conversations may be initiated within a transaction. Start the conversation as part of the program statements in transaction mode. For more information on transactions, see WebLogic Tuxedo Connector JATMI Transactions.
  • If a WebLogic Tuxedo Connector remote domain experiences a TPENOENT, the remote domain will send back a disconnect event message and be caught on the WebLogic Tuxedo Connector application tprecv as a TPEV_DISCONIMM exception.

Skip navigation bar  Back to Top Previous Next