Developing WebLogic Tuxedo Connector Client EJBs

 

Note: For more information on the WebLogic Tuxedo Connector JATMI, view the Javadocs for WebLogic Server Classes. The WebLogic Tuxedo Connector classes are located in the weblogic.wtc.jatmi and weblogic.wtc.gwt packages.

The following sections describe how to create client EJBs that take user input and send service requests to a server process or outbound object that offers a requested service.

• Joining and Leaving Applications

• Basic Client Operation

• Example Client EJB

WebLogic Tuxedo Connector JATMI client classes are used to create clients that access services found in Tuxedo.

 

---

Joining and Leaving Applications

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

Joining an Application

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

• Tuxedo uses tpinit() to join an application.

• WebLogic Tuxedo Connector uses the BDMCONFIG XML configuration file to provide information required to create a path to the Tuxedo service. It provides security and client authentication by configuring the T_DM_REMOTE_TDOMAIN and T_DM_IMPORT sections of the BDMCONFIG XML configuration file. This pathway is created when the WebLogic Server is started and the WebLogic Tuxedo Connector XML configuration file is loaded.

• WebLogic Tuxedo Connector uses TuxedoConnection to get a Tuxedo object and then uses getTuxedoConnection() to make a connection to the Tuxedo object. The following example shows how a WebLogic Server application joins a Tuxedo application using WebLogic Tuxedo Connector.

  Listing 2-1 Example Client Code to Join a 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();
  .
  .
  .
  

Leaving an Application

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

• Tuxedo uses tpterm() to leave an application.

• WebLogic Tuxedo Connector uses the JATMI primitive tpterm() to close a connection to a Tuxedo object.

• WebLogic Tuxedo Connector closes the pathway to a Tuxedo service when the WebLogic Server is shutdown.

 

---

Basic Client Operation

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

• Get a Tuxedo Object

• Perform Message Buffering

• Send and Receive Messages

• Close a Connection to a Tuxedo Object

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

Get a Tuxedo Object

Establish a connection to a remote domain by using the TuxedoConnectionFactory to lookup "tuxedo.services.TuxedoConnection" in the JNDI tree and get a TuxedoConnection object using getTuxedoConnection().

Perform Message Buffering

Use the following buffer types when sending and receiving messages between your application and 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. Tuxedo equivalent: STRING.
TypedCArray	Buffer type used when the data is an undefined array of characters (byte array), any of which can be null. 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. Tuxedo equivalent: FML.
TypedFML32	Buffer type similar to TypeFML but allows for larger character fields, more fields, and larger overall buffers. Tuxedo equivalent: FML32.
TypedXML	Buffer type used when data is an XML based message. Tuxedo equivalent: XML for Tuxedo Release 7.1 and higher.

Send and Receive Messages

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

• Request/Response Communication

• Conversational Communication

Request/Response Communication

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

Table 2-2 JATMI Primitives

Name	Operation
tpacall	Use for asynchronous invocations of a Tuxedo service.
tpcall	Use for synchronous invocation of a Tuxedo service.
tpdequeue	Use for receiving messages from a Tuxedo /Q.
tpenqueue	Use for placing a message on a Tuxedo /Q.
tpgetrply	Use for retrieving replies from a Tuxedo service.

Conversational Communication

Note: For more information on Conversational Communication, see WebLogic Tuxedo Connector JATMI Conversations.

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

Table 2-3 WebLogic Tuxedo Connector Conversational Client Primitives

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 when executed by the process controlling the conversation.
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.

Close a Connection to a Tuxedo Object

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

 

---

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.

Listing 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());
}
.
.
.