Developing Oracle WebLogic Tuxedo Connector Client EJBs

2 Developing Oracle WebLogic Tuxedo Connector Client EJBs

This chapter describes how to create Oracle WebLogic Tuxedo Connector client EJBs. These client EJBs take user input and send service requests to a server process or outbound object that offers a requested service. Oracle WebLogic Tuxedo Connector JATMI client classes are used to create clients that access services found in Oracle Tuxedo.

Note:

See Javadocs for WebLogic Classes for more information on the Oracle WebLogic Tuxedo Connector JATMI. The Oracle WebLogic Tuxedo Connector classes are located in the weblogic.wtc.jatmi and weblogic.wtc.gwt packages.

This chapter includes the following sections:

Joining and Leaving Applications

Oracle Tuxedo and Oracle WebLogic Tuxedo Connector have different approaches to connect to services.

Parent topic: Developing Oracle WebLogic Tuxedo Connector Client EJBs

Joining an Application

The following section compares how Oracle Tuxedo and Oracle WebLogic Tuxedo Connector join an application:

Oracle Tuxedo uses tpinit() to join an application.
Oracle WebLogic Tuxedo Connector uses a WTCServer MBean to provide information required to create a path to the Oracle Tuxedo service. Security and client authentication is provided by configuring the Remote TDM and Imported Services MBean components of a WTCServer MBean. This pathway is created when the Oracle WebLogic Server is started and a WTCServer MBean is present in the config.xml file and assigned (targeted) to a server.
Oracle WebLogic Tuxedo Connector uses TuxedoConnectionFactory to get a TuxedoConnection object and then uses getTuxedoConnection() to make a connection to the Oracle Tuxedo object. The following example shows how a Oracle WebLogic Server application joins an Oracle Tuxedo application using Oracle WebLogic Tuxedo Connector.

Example 2-1 Example Client Code to Join an Oracle Tuxedo Application

.
.
.
try {
     ctx = new InitialContext();
     tcf = 
          (TuxedoConnectionFactory)
          ctx.lookup("tuxedo.services.TuxedoConnection");
     } catch (NamingException ne) {

// Could not get the tuxedo object, throw TPENOENT
throw new TPException(TPException.TPENOENT, 
     "Could not get TuxedoConnectionFactory : " + ne);
     } 

myTux = tcf.getTuxedoConnection();
.
.
.

Parent topic: Joining and Leaving Applications

Leaving an Application

The following section compares how Oracle Tuxedo and Oracle WebLogic Tuxedo Connector leave an application:

Oracle Tuxedo uses tpterm() to leave an application.
Oracle WebLogic Tuxedo Connector uses the JATMI primitive tpterm() to close a connection to an Oracle Tuxedo object.
Oracle WebLogic Tuxedo Connector closes the pathway to an Oracle Tuxedo service when a WTCServer MBean is assigned a new target server or the server is shutdown.

Parent topic: Joining and Leaving Applications

Basic Client Operation

A client may send and receive any number of service requests before leaving the application.

A client process uses Java and JATMI primitives to provide the following basic application tasks:

Parent topic: Developing Oracle WebLogic Tuxedo Connector Client EJBs

Get an Oracle Tuxedo Object

Establish a connection to a remote domain by looking up tuxedo.services.TuxedoConnection in the JNDI tree to get TuxedoConnectionFactory, and use it to get a TuxedoConnection object.

Parent topic: Basic Client Operation

Perform Message Buffering

Use the following TypedBuffers when sending and receiving messages between your application and Oracle Tuxedo:

Table 2-1 TypedBuffers

Buffer Type	Description
`TypedString`	Buffer type used when the data is an array of characters that terminates with the null character. Oracle Tuxedo equivalent: `STRING`.
`TypedCArray`	Buffer type used when the data is an undefined array of characters (byte array), any of which can be null. Oracle Tuxedo equivalent: `CARRAY`.
`TypedFML`	Buffer type used when the data is self-defined. Each data field carries its own identifier, an occurrence number, and possibly a length indicator. Oracle Tuxedo equivalent: `FML`.
`TypedFML32`	Buffer type similar to TypeFML but allows for larger character fields, more fields, and larger overall buffers. Oracle Tuxedo equivalent: `FML32`.
`TypedXML`	Buffer type used when data is an XML based message. Oracle Tuxedo equivalent: XML for Tuxedo Release 7.1 and higher.
`TypedView`	Buffer type used when the application uses a Java structure to define the buffer structure using a view description file. Oracle Tuxedo equivalent: `View`.
`TypedView32`	Buffer type similar to View but allows for larger character fields, more fields, and larger overall buffers. Oracle Tuxedo equivalent: `View32`.
`TypedMBString`	Buffer type used when the data is a wide array of characters to support multi-byte characters. Oracle Tuxedo equivalent: `MBSTRING`.

Parent topic: Basic Client Operation

Send and Receive Messages

Oracle WebLogic Tuxedo Connector clients support three types of communications with Oracle Tuxedo service applications:

Parent topic: Basic Client Operation

Request/Response Communication

Note:

Oracle WebLogic Tuxedo Connector does not provide a JATMI primitive to support setting the priority of a message request. All messages originating from a Oracle WebLogic Tuxedo Connector client have a message priority of 50.

Use the following JATMI primitives to request and receive response messages between your Oracle WebLogic Tuxedo Connector client application and Oracle Tuxedo:

Table 2-2 JATMI Primitives

Name	Operation
`tpacall`	Use for asynchronous invocations of an Oracle Tuxedo service. This JATMI primitive has two forms: deferred synchronous asynchronous
`tpacall`	Use for synchronous invocation of an Oracle Tuxedo service.
`tpgetrply`	Use for retrieving replies from deferred synchronous calls to an Oracle Tuxedo service.
`tpcancel`	Use to cancel an outstanding message reply for a call descriptor returned by `tpacall`. Note: You can not use `tpcancel` to cancel a call descriptor associated with a transaction.

Parent topic: Send and Receive Messages

Using Synchronous Service Calls

Use tpcall to send a request to a service and synchronously await for the reply. The service specified must be advertised by your Oracle Tuxedo application. Logically, tpcall() has the same functionality as calling tpacall() and immediately calling tpgetreply().

Parent topic: Request/Response Communication

Using Deferred Synchronous Service Calls

A deferred synchronous tpacall allows you to send a request to an Oracle Tuxedo service and not immediately wait for the reply. This allows you to send a request, perform other work, and then retrieve the reply.

A deferred tpacall() service call sends a request to an Oracle Tuxedo service and immediately returns from the call. The service specified must be advertised by your Oracle Tuxedo application. Upon successful completion of the call, tpacall() returns an object that serves as a descriptor. The calling thread is now available to perform other tasks. You can use the call descriptor to:

Get the correct reply for the sent request using tpgetreply()
Cancel an outstanding message reply using tpcancel().

When you are ready to retrieve the reply, use tpgetreply() to dequeue the reply using the call descriptor returned by tpacall(). If the reply is not immediately available, the calling thread polls for the reply.

If tpacall() is in a transaction, you must receive the reply using tpgetreply() before the transaction can commit. You can not use tpcancel to cancel a call descriptor associated with a transaction. For example: If you make three tpacall() requests in a transaction, you must make three tpgetreply() calls and successfully dequeue a reply for each of the three requests for the transaction to commit.

Parent topic: Request/Response Communication

Using Asynchronous Calls

The asynchronous tpacall allows you to send a request to an Oracle Tuxedo service and release the thread resource that performed the call to the thread pool. This allows a very large number of outstanding requests to be serviced with a much smaller number of threads.

An asynchronous tpacall() service call sends a request to an Oracle Tuxedo service. The service specified must be advertised by your Oracle Tuxedo application. Upon successful completion of the call, asynchronous tpacall() returns an object that serves as a descriptor. The calling thread is now available to perform other tasks. You can use the call descriptor to identify the correct message reply from TpacallAsynchReply for a sent message request or cancel an outstanding message reply using tpcancel().

Note:

You can not use the call descriptor to invoke tpgetreply().

When the service reply is ready, the callback object is invoked on a different thread. If the original request succeeded, the TpacallAsynchReply.sucess method returns the reply from the service. If the original request failed, the TpacallAsynchReply.failure method returns a failure code.

You should implement the callback object using the following guidelines:

The reply thread is obtained from the threadpool. The thread making the asynchronous tpacall() does not wait for the reply message.
The user context of the reply thread will be restored to that of the original caller of asynchronous tpacall().
It is up to the callback object to restore any additional context and resume whatever processing was interrupted when the original asynchronous tpacall() was made.
It is up to you to synchronize work within the multi threaded environment. For example: If an asynchronous tpacall() request is made and the reply is returned immediately, it is possible for the call back object to be modified by the reply thread before the calling thread has finished.
The reply thread will not retain the transaction context of the calling thread.
If asynchronous tpacall() is in a transaction, you must receive the reply using TpacallAsynchReply before the transaction can commit. You can not use tpcancel to cancel a call descriptor associated with a transaction.

Parent topic: Request/Response Communication

Conversational Communication

Note:

See Oracle WebLogic Tuxedo Connector JATMI Conversations for more information on Conversational Communication.

Use the following conversational primitives when creating conversational clients that communicate with Oracle Tuxedo services:

Table 2-3 Oracle WebLogic Tuxedo Connector Conversational Client Primitives

Name	Operation
`tpconnect`	Use to establish a connection to an Oracle Tuxedo conversational service.
`tpdiscon`	Use to abort a connection and generate a TPEV_DISCONIMM event when executed by the process controlling the conversation.
`tprecv`	Use to receive data across an open connection from an Oracle Tuxedo application.
`tpsend`	Use to send data across an open connection to an Oracle Tuxedo application.

Parent topic: Send and Receive Messages

Enqueuing and Dequeuing Messages

Use the following JATMI primitives to enqueue and dequeue messages between your Oracle WebLogic Tuxedo Connector client application and Oracle Tuxedo:

Table 2-4 JATMI Primitives

Name	Operation
`tpdequeue`	Use for receiving messages from an Oracle Tuxedo /Q.
`tpenqueue`	Use for placing a message on an Oracle Tuxedo /Q.

Parent topic: Send and Receive Messages

Close a Connection to an Oracle Tuxedo Object

Use tpterm() to close a connection to an object and prevent future operations on this object.

Parent topic: Basic Client Operation

Example Client EJB

The following Java code provides an example of the ToupperBean.java client EJB which sends a string argument to a server and receives a reply string from the server.

Example 2-2 Example Client Application

.
.
.
public String Toupper(String toConvert)
   throws TPException, TPReplyException
{
     Context ctx;
     TuxedoConnectionFactory tcf;
     TuxedoConnection myTux;
     TypedString myData;
     Reply myRtn;
     int status;

     log("toupper called, converting " + toConvert);

     try {
          ctx = new InitialContext();
          tcf = (TuxedoConnectionFactory) ctx.lookup(
                "tuxedo.services.TuxedoConnection");
     }
     catch (NamingException ne) {
          // Could not get the tuxedo object, throw TPENOENT
           throw new TPException(TPException.TPENOENT, "Could not get
           TuxedoConnectionFactory : " + ne);
     }

     myTux = tcf.getTuxedoConnection();

     myData = new TypedString(toConvert);

     log("About to call tpcall");
     try {
          myRtn = myTux.tpcall("TOUPPER", myData, 0);
}
     catch (TPReplyException tre) {
          log("tpcall threw TPReplyExcption " + tre);
          throw tre;
     }
     catch (TPException te) {
          log("tpcall threw TPException " + te);
          throw te;
     }
     catch (Exception ee) {
          log("tpcall threw exception: " + ee);
          throw new TPException(TPException.TPESYSTEM, "Exception: " + ee);
     }
     log("tpcall successfull!");

     myData = (TypedString) myRtn.getReplyBuffer();

     myTux.tpterm();// Closing the association with Tuxedo

     return (myData.toString());
}
.
.
.

Parent topic: Developing Oracle WebLogic Tuxedo Connector Client EJBs