JATMI Programming

下文图片并没有展示，具体文章地址可以从以下链接打开。本来是想翻译下这个文章，但是这个是weblogic8的，算是过时的了，但还是有参考价值的。

http://82.157.70.109/mirrorbooks/beaweblogic8.1/0672324873_ch34lev1sec1.html

Now let's get to building applications using WTC. As mentioned earlier, the JATMI provides the interface between WebLogic and Tuxedo applications. The building blocks of programming using JATMI are

• ATMI primitives

• Typed buffers

The JATMI primitives are very similar to the Tuxedo ATMI primitive calls and are simple Java-based APIs. These APIs enable the communication between WebLogic Server and Tuxedo as well as provide APIs to manage transactions and manipulate proprietary typed buffers. We'll look at the available APIs later in the chapter when we get to implementing WTC-based Tuxedo clients.

The JATMI typed buffers are the WTC equivalent of the Tuxedo ATMI typed buffers and are used for transporting data to the service calls. Table 34.1 summarizes the typed buffers of WTC and Tuxedo.

Table 34.1. Communication Buffers

JATMI	Tuxedo	Description
TypedString	STRING	Character array terminated by NULL
TypedCArray	CARRAY	Byte array
TypedFML	FML	Well-defined data type including occurrence, length, and identifier
TypedFML32	FML32	Similar to FML, but provides bigger buffers
TypedXML	XML	XML-based message buffer
TypedView	View	View description file-based buffer
TypedView32	View32	Similar to View with bigger buffers

We'll now move to developing clients based on the JATMI programming basics we've covered so far. Many different client types can be created, depending on the communication type used with the Tuxedo Server.

NOTE

As mentioned earlier, it's assumed that you have some basic working knowledge of Tuxedo: developing, configuring and maintaining a simple Tuxedo domain. For learning how to do those things, refer to http://edocs.bea.com/tuxedo/tux81/interm/atmiprog.htm. When fully installed, Tuxedo software comes with a basic set of examples covering the different features of the software. One of the sample applications is a simple bank application: bankapp. This C-based application is an ATMI application and the services defined as part of the application are basic account-related operations. The functions performed are opening and closing accounts, inquiring on balances, and withdrawing, depositing, and transferring funds from one account to another. For a full tutorial of how to use bankapp, refer tohttp://edocs.bea.com/tuxedo/tux81/tutor/tutba.htm.

Let's now discuss the process of building a simple JATMI client for accessing the INQUIRY Tuxedo service that's part of the bank application described earlier. INQUIRY Tuxedo service returns the account balance for a given account number.

Basic Configuration

Let's start by creating a connection between the WebLogic Server and the Tuxedo domain running our sample Tuxedo application (bankapp). The connection creation mechanism is different from regular Tuxedo clients that use the ATMI function tpinit() to connect to the Tuxedo domain. With WTC, the connection is created at startup using a WTCServer MBean. The WTCServer MBean uses the configuration parameter defined by the user as part of the startup and creates the connections to the remote domain.

NOTE

All WTC configuration parameters are defined in the config.xml file.

WTC configuration can be performed using the WebLogic console. Figure 34.2 describes how to define the WTCServer base configuration. As the figure indicates, we create a WTCServer with MyWTCService as the name; this has to be attached to a target WebLogic Server.

Figure 34.2. Define a WTC server.

After defining the WTC server within the WebLogic environment, we must name the local access point (port) that's used for communicating with the back-end Tuxedo server. Figure 34.3 describes how to define the local Tuxedo access point.

Figure 34.3. Local Tuxedo access point.

Finally, we must configure the port number in the remote Tuxedo domain that is listening to the WebLogic Server–based requests. Figure 34.4 describes how to define the remote Tuxedo access point.

Figure 34.4. Remote Tuxedo access point.

At the end of this process, the config.xml file would be updated with the WTCServer MBean configuration and be ready for opening up Tuxedo services such as balance inquiry in our sample bank application. The next step in the process is to import the services from the remote Tuxedo domain. Because we aren't exposing services in the WebLogic Server to the Tuxedo world, there's no need for any services to be exported. Figure 34.5 shows how to import a remote Tuxedo service. We're importing the INQUIRY Tuxedo service that's advertised as part of the sample bank application.

Figure 34.5. Importing services.

The following XML snippet gives you an idea of the WTCServer MBean configuration after executing the aforementioned steps:

NOTE

The Interoperate attribute in WTCLocalTuxDom helps to integrate WTC services with Tuxedo services defined in an earlier version of Tuxedo (6.5).

As you can see from the configuration file snippet, we've defined the following parameters:

• Remote domain parameters, including the network address and connection policy

• Local domain parameters

• Imported remote services and exported remote services

The Connection policy parameter set up as part of the WTCRemoteTuxDom / WTCLocalTuxDom MBean determines the conditions under which the local domain connects to the remote domain. Valid values for the parameter are

• ON_DEMAND— A connection is attempted only when requested by either of the domain services—either a client request or an administrative request. This is the default setting.

• ON_STARTUP— A domain gateway attempts to establish a connection with its remote domain access points at gateway server initialization time.

• INCOMING_ONLY— A domain gateway does not attempt an initial connection to remote domain access points at startup and remote services are initially suspended. When the domain gateway of the local domain access point receives an incoming connection, a connection is made and services are advertised if successful.

The interoperate attribute inside WTCLocalTuxDom is a special attribute that enables a local Tuxedo access point to interoperate with remote Tuxedo domains that run on versions earlier than 6.5. The earlier configuration sets up a simple connection between WebLogic Server and a remote Tuxedo domain. Other parameters within each of the MBean configurations can be added for increased security, encryption, and so on. WebLogic Tuxedo Connector configuration is managed by the set of MBeans defined in Table 34.2.

Table 34.2. WTC Configuration MBeans

MBean	Description
WTCServer	The parent WTC MBean used for setting the interoperability attributes required for WTC–Tuxedo domain connectivity.
WTCLocalTuxDom	Defines the properties of the local domain.
WTCRemoteTuxDom	Defines the properties of the remote domain.
WTCExport	Provides information about the services available in the local domain. This is an optional bean configuration. If unspecified, all services are advertised to the external domains.
WTCImport	Provides information about services imported and available on remote domains.
WTCPassword	Provides information for interdomain authentication through access points of type TDOMAIN.
WTCResources	Defines the FML and VIEW field tables and application passwords for the domain.
WTCtBridgeGlobal	Provides global configuration information and advanced messaging between WebLogic Server and Tuxedo.
WTCtBridgeRedirect	Provides the source, target, direction, and transport of a message.

For detailed information about the list of attributes for the MBeans we've used and the ones listed in Table 34.2, refer to http://edocs.bea.com/wls/docs81/config_xml/index.html.

The Tuxedo system administrator has to make some changes depending on the setup of the remote Tuxedo system. As you can see from the earlier configuration, WTC requires a remote /T domain to be configured as part of the Tuxedo application. Refer to the BEA Tuxedo domains guide at http://edocs.bea.com/tuxedo/tux81/interm/admin.htm#dom for more information about Tuxedo domains (/T domains). If the existing Tuxedo application does not have a domain set up (like our bank application), a new domain must be configured to correspond to the remote access point in the WTCServer MBean. If the existing Tuxedo application already has domains set up, the Tuxedo administrator has to make sure that a domain configuration matches the remote access point defined as part of the WTCServer MBean. The changes to the Tuxedo domain can be summarized as follows:

• Add the required group definitions for the domain administration server and the gateway domain servers in the Tuxedo configuration file (that is, the UBB file):

  *GROUPS
  DMADMGRP  LMID=SITE1 GRPNO=100
  DMGRP  LMID=SITE1 GRPNO=200
  

• Add the domain administrative server and gateway domain servers to the list of servers available as part of the Tuxedo application:

        *SERVERS
  DMADM    SRVGRP=DMADMGRP SRVID=200
  GWADM    SRVGRP=DMGRP  SRVID=220
  GWTDOMAIN  SRVGRP=DMGRP  SRVID=240
  

• The last step is to configure the Tuxedo domain configuration that has been already set up as the remote access point in the WebLogic Server environment:

  #
  *DM_LOCAL_DOMAINS
  #
  TDOM1 GWGRP=DMGRP
  TYPE=TDOMAIN
  DOMAINID="TDOM1"
  BLOCKTIME=10
  MAXDATALEN=56
  MAXRDOM=89
  DMTLOGDEV="[LOGDIR]/bankApp_dm"
  AUDITLOG="[LOGDIR]/bankApp_aud"
  DMTLOGNAME="DMTLOG_BANKAPP"
  CONNECTION_POLICY="ON_STARTUP"
  #
  *DM_REMOTE_DOMAINS
  #
  #
  TDOM2   TYPE=TDOMAIN
    DOMAINID="TDOM2"
  #
  #
  *DM_TDOMAIN
  #
  TDOM1 NWADDR="//175.18.26.24:5966"
      NWDEVICE="/dev/tcp"
  TDOM2 NWADDR="//47.11.30.28:5966"
      NWDEVICE="/dev/tcp"
  #
  *DM_LOCAL_SERVICES
       INQUIRY LDOM="TDOM1"

Establishing a Connection

Now we've set up the Tuxedo connections. Let's get down to writing some client code. The Tuxedo connections established as part of the startup process are registered in the JNDI under the nametuxedo.services.TuxedoConnection. A TuxedoConnection object can be obtained using the getTuxedoConnection() method of TuxedoConnectionFactory, which gives the live Tuxedo connection to the client:

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

Before we get to use this Tuxedo connection, let's take a step back and learn about one of the important features of BEA Tuxedo: the Field Manipulation Language (FML). Table 34.1 listed the message buffers that are available as part of the Tuxedo system. FML-based buffers (FML and FML32) represent the most used Tuxedo buffers for data exchange between the client and the Tuxedo service. Let's look at programming FML buffers; we'll use them to implementing the bankapp client using WTC.

Field Manipulation Language Programming

FML is a well-defined set of buffer management functions for efficient transfer of data between Tuxedo components. FML contains attribute-value pairs called fields. The attribute is a field identifier and the value represents the corresponding content. Additionally, FML facilitates multiple occurrences of an attribute-value pair. In other words, FML can be considered as a three-dimensional hash table, where the third dimension is the occurrence of a field. FML provides named access to the fields used in the communication between the processes involved in the Tuxedo domain.

FML—Size Does Matter

FML comes in two sizes. The original version of the buffer (FML16) is based on a 16-bit value for the length of the fields. It also limits the number of fields that can be defined to 8191 unique fields. The individual field lengths can be up to 64K bytes and a total buffer size of 64KB. FML32 allows for about 30 million fields and field and buffer lengths of about 2 billion bytes.

FML in WTC

FML in WTC is a limited implementation of the full FML capability. Table 34.3 summarizes the field types and the associated object types supported by FML.

Table 34.3. FML Field Types and Objects

Field Types	Object Equivalent
FLD_SHORT	Short
FLD_LONG	Long
FLD_CHAR	Character
FLD_FLOAT	Float
FLD_DOUBLE	Double
FLD_STRING	String
FLD_CARRAY	byte[]
FLD_FML32	TypedFML32
FLD_PTR	TypedBuffer

FLD_VIEW32, FLD_INT, and FLD_DECIMAL are not yet supported.

The FML fields used in the buffer should be defined in a field table. Listing 34.1 lists a section of the bank application field table that's defined as part of the bank application Tuxedo example.

Listing 34.1 Bank Application Field Tables (bankflds)

#FML
# Fields for database bankdb
# name             number type  flags  comments
ACCOUNT_ID           110   long  -    -
ACCT_TYPE           112   char  -    -
ADDRESS            109   string -    -
AMOUNT             117   float  -    -
BALANCE            105   float  -    -
TELLER_ID           116   long  -    -
#
# non database fields
SBALANCE            201   string -    dollar format
SAMOUNT            202   string -    dollar format
#END

The field table defined in Listing 34.1 has to be converted into a Java class before implementing the corresponding WTC—Tuxedo client. WTC provides utility classes—mkfldclass and mkfldclass32—as part of thewebLogic.wtc.jatmi package. The utility produces a Java class that implements the FldTbl interface. The following command is used to generate the Java class:

java weblogic.wtc.jatmi.mkfldclass wlsunleashed.wtc bankflds

The second argument to the command is the package name for the generated field table class and third argument is the field table's filename. Listing 34.2 shows parts of the generated Java file. As you can see, the field names defined in Listing 34.1 are converted to Java final native types that can be referenced in the WTC Tuxedo client code.

Listing 34.2 Generated Java Equivalent of bankflds

package wlsunleashed.wtc;

import java.io.*;
import java.lang.*;
import java.util.*;
import weblogic.wtc.jatmi.*;

public final class bankflds
    implements weblogic.wtc.jatmi.FldTbl
{
    Hashtable nametofieldHashTable;
    Hashtable fieldtonameHashTable;

    /** number: 110 type: long */
    public final static int ACCOUNT_ID = 8302;
    /** number: 112 type: char */
    public final static int ACCT_TYPE = 16496;
    /** number: 109 type: string */
    public final static int ADDRESS = 41069;
...
...
   public String Fldid_to_name(int fldid)
    {
        if ( fieldtonameHashTable == null ) {
            fieldtonameHashTable = new Hashtable();
            fieldtonameHashTable.put(new Integer(ACCOUNT_ID), "ACCOUNT_ID");
...
...
...
   }
   public int name_to_Fldid(String name)
    {
        if ( nametofieldHashTable == null ) {
            nametofieldHashTable = new Hashtable();
            nametofieldHashTable.put("ACCOUNT_ID", new Integer(ACCOUNT_ID));
            nametofieldHashTable.put("ACCT_TYPE", new Integer(ACCT_TYPE));
            nametofieldHashTable.put("ADDRESS", new Integer(ADDRESS));
...
...
...
    }

}

After bankflds.java is compiled, the resulting class must be added to the classpath of the application. The WTCResources MBean has to be updated at this point to include the generated class file. Figure 34.6shows how to add this resource to the configuration.

Figure 34.6. Configuring WTC resource files.

The following XML snippet shows the configuration of the WTCResources MBean after adding our FML field table class file:

The bankflds class implements weblogic.wtc.jatmi.FldTbl—this is a common interface that can be used by both FML16 and FML32 buffers. Using a common interface simplifies the applications implementing it and provides the capability to easily switch between the buffers if needed.

Let's move to manipulating the FML buffers. The weblogic.wtc.jatmi.FML is the main FML interface used by both FML16 and FML32 buffers. The main functions defined by this interface are needed for populating, deleting, and extracting fields from a FML buffer. They are Fchg, Fdel, and Fget, respectively.

• Fchg adds the given object to the FML buffer whose ID is contained in the key to the fielded buffer. The key includes the occurrence of the field.

• Fdel deletes the particular occurrence from the fielded buffer.

• Fget retrieves a copy of the object stored in the FML buffer of the given field ID and the occurrence.

The interface also provides functions for retrieving the field number, field types, and names. Subinterfaces to this FML interface correspond to the size of the FML buffer: TypedFML and TypedFML32. These interfaces add more functionality to the FML interfaces pertaining to buffer manipulation, including Fadd. Fadd is also used to add fields to the buffer. As you can see, all the described functions are exactly mapped to a corresponding Tuxedo function. For more information about the FML and subinterfaces, refer to http://edocs.bea.com/wls/docs81/javadocs/weblogic/wtc/jatmi/package-tree.html. Now let's move on to using some of the functions in the bank application WTC client.

Input Typed Buffers

The inputs to service requests are packed into the message buffers defined in Table 34.1. The INQUIRY Tuxedo service requires the inputs (namely the account number) to be sent in an FML buffer. The first step in using a typed buffer is to create it. This is a common step with every typed buffer. Let's look at two types of typed buffer creation.

If the typed buffer being used is TypedString, the creation of the buffer is simple:

myData = new TypedString(myInputString);

In the case of our client, we need to create a FML16 buffer as follows:

TypedFML myData = new TypedFML(new bankflds());

An instance of the field table class we created earlier has to be passed to the TypedFML constructor. At this time, the buffer is ready to populated. The input to the INQUIRY service is the account number of the customer, which returns the balance along with the account number. The following code snippet populates the input FML buffer with the account number:

try {
  myData.Fchg(bankflds.ACCOUNT_ID,0, new Integer(getId()));
} catch (Ferror fe) {
  log("An error occurred putting data into the FML buffer. The error is "
    + fe);
 }

The arguments to the Fchg function are the field name (as defined by the field table class), field repetition (occurrence), and field value. Each FML field can be repeated multiple times in the same FML buffer. Now let's discuss how to use the created buffer and invoke a Tuxedo service to perform the requested function.

Invoking Tuxedo Services

WebLogic Tuxedo Connector supports the following communication mechanisms with a remote Tuxedo domain:

• Request-response communication

• Conversational communication

• Queue-based communication (enqueue and dequeue)

Request-Response Communication

In the request-response mode, a software module acting as a client sends requests to a server and waits for a response. The response can be returned either synchronously or asynchronously. JATMI provides APIs for both asynchronous and synchronous request-response models.

The JATMI call tpcall is used for synchronous request-response mode. The INQUIRY service call sends the account balance request and waits for the response without proceeding to other tasks. Listing 34.3describes how the service call is made and the exceptions it must handle. The return value (myRtn) to the service call is also a typed buffer, which is explained later in the chapter. The exceptions generated are also explained later in the chapter.

Listing 34.3 Service Invocation

try {
   myRtn = myTux.tpcall("INQUIRY", 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);
}

Alternatively, the service call could have been made asynchronously. In this case, the client need not wait for the response to come back and can proceed to other tasks. The client can come back later and fetch the response using a call descriptor. The call descriptor is returned as part of the service invocation. The JATMI calls that are used in an asynchronous mode are

• tpacall— Invokes the Tuxedo services asynchronously

• tpgetreply— Retrieves replies of previously made asynchronous calls

• tpcancel— Cancels a previously issued asynchronous call (nontransactional) identified by a call descriptor

Conversational Communication

In conversational communication, a half-duplex communication channel is kept open between the WTC and the Tuxedo domain conversational server. The initiator is the process that controls the message send; the subordinate process can only receive messages. The initiator and the subordinate hold state information related to the state of the conversation. A logical connection stays alive until a termination event takes place. A single conversation can involve any number of messages between the initiator and the subordinate. Figure 34.7 describes the steps involved in a conversational service invocation from WTC into the Tuxedo domain. Establishment of the connection between the servers is similar to the mechanism described for request-response mode.

Figure 34.7. WTC in a conversational communication.

The lists of JATMI calls, which are used in a conversational mode, are

• tpsend— Sends messages to the conversational server

• tprecv— Receives messages on an open communication channel

• tpdiscon— Generates the event to disconnect the conversation

These functions are exposed to the WTC conversational client using the weblogic.wtc.jatmi.TPServiceInformation class, which implements a weblogic.wtc.jatmi.Conversation interface.

Queue-Based Communication

In addition to the preceding types of calls, messages can also be sent asynchronously to the Tuxedo service with the use of Tuxedo /Q. The weblogic.wtc.jatmi.EnqueueRequest class provides the same functionality as that of its Tuxedo equivalent, tpenqueue(). It places requests on the configured Tuxedo queue for processing by the requested Tuxedo service. Similarly, weblogic.wtc.jatmi.DequeueReply processes replies from Tuxedo for a previously queued request. It performs the same function as the Tuxedo equivalent (tpdequeue). This exactly extends the /Q interfaces to the WebLogic Server environment.

Exceptions Framework

The WebLogic Tuxedo Connector handles exceptions using the following classes.

Ferror

This exception is thrown when manipulating the FML buffer; such as when adding, deleting, and changing elements to the buffer.

TPException

This exception represents all TPException failures. All exceptions of this type are generated by the core WTC calls, such as tpcall, tpacall, tpenqueue, tpdequeue, and so on. This exception class provides methods that give the details about the system failure. It also provides getReplyRtn method to give the data that's associated with the system failure.

TPReplyException

This exception is used when throwing an exception from the Tuxedo service interface. The error object should indicate the Tuxedo error code: TPESVCERR or TPESVCFAIL. It also provides a ReplyRtn object, which can contain user data to be returned in the failure case and the tpurcode to be returned.

Output Processing

Output from service requests is packed into the message buffers defined in Table 34.1. The INQUIRY Tuxedo service returns the outputs (account balance) in an FML buffer. The following code snippet explains how to extract the information from the returned buffer. The FML buffer interface provides the Fget() function to extract the values from the buffer.

myDataBack = (TypedFML) myRtn.getReplyBuffer();
try {
  balance = (String) myDataBack.Fget(bankflds.SBALANCE, 0);
} catch (Ferror fe) {
 log("An error occurred getting data from the FML32 buffer. The error is "+ fe);
}

After the service calls are completed over the initiated connection, the connection should be released using the tpterm() call as demonstrated here:

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

Complete Example of a WTC Client

So far, we've seen the pieces of WTC client. Now let's put all those pieces together. Listing 34.4 is a complete example of a WTC client. This code can be used inside any of the J2EE components (for example, EJBs and servlets) to invoke a Tuxedo service.

Listing 34.4 WTC Client

public String getBalance() throws TPException, TPReplyException {
   String balance = "";
   Context ctx;
   TuxedoConnectionFactory tcf;
   TuxedoConnection myTux;
   TypedFML myData;
   TypedFML myDataBack;
   Reply myRtn;
   int status;

   try {
     ctx = getInitialContext();
     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 TypedFML(new bankflds());
   try {
      myData.Fchg(bankflds.ACCOUNT_ID,0, new Integer(getId()));
   } catch (Ferror fe) {
      log("An error occurred putting data into the FML32 buffer.
      The error is " + fe);
   }
   try {
     myRtn = myTux.tpcall("INQUIRY", 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("INQUIRY tpcall successful!");

   myDataBack = (TypedFML) myRtn.getReplyBuffer();

   try {
     balance = (String) myDataBack.Fget(bankflds.SBALANCE, 0);
   } catch (Ferror fe) {
     log("An error occurred getting data from the FML32 buffer.
       The error is " + fe);
   }
   myTux.tpterm(); // Closing the association with Tuxedo
   return balance;
}

WTC Service EJB

We've already talked about invoking a remote Tuxedo service from a WebLogic Server–based J2EE component. JATMI also provides the infrastructure needed to implement a service EJB that can be invoked from a remote Tuxedo domain. Let's examine the steps involved in implementing a simple service EJB that can be invoked from a remote Tuxedo domain.

Implementing a Service EJB

The first step in the implementation of the service EJB is to identify the service and the input data. We also need to identify the special flags associated with the service execution. Theweblogic.wtc.jatmi.TPServiceInformation class provides all this information using the functions defined in Table 34.4.

Table 34.4. TPServiceInformation Functions

Service Information Functions	Description
getServiceData	Returns a TypedBuffer that can be type-cast to the appropriate buffer as defined in Table 34.1
getServiceName	Returns the name of the service
getServiceFlags	Returns the flags associated with this service

This class also provides the methods to implement the conversational server. All buffers defined in Table 34.1 can be used to pass the data from the Tuxedo client to the server.

Listing 34.5 displays the main function associated with the Hello World service EJB. As you can see in the first line, the argument to the service method is an instance of TPServiceInformation class. This instance is used in the function body to obtain the service input and metadata information such as the service name. Also, the return value for this function is an object that implements weblogic.wtc.jatmi.Reply. The input argument type—TPServiceInformation—is a subclass of weblogic.wtc.jatmi.TuxedoReply that implements the Reply interface. So, the same buffer can be used to send the output back to the calling Tuxedo domain.

Listing 34.5 Hello World Service EJB

public Reply service(TPServiceInformation mydata) throws TPException {
   TypedString data;
   String name;
   TypedString greeting;

   data = (TypedString) mydata.getServiceData();
   greeting = "Hello World" + data.toString().toLowerCase();
   data = new TypedString(greeting);

   mydata.setReplyBuffer(return_data);
   return (mydata);
}

JATMI Transactions

WebLogic Tuxedo Connector supports outbound transactions propagation from WebLogic into the Tuxedo domain. WTC uses the Java Transaction API (JTA) to manage transactions.

Transactions can be defined with the WTC client classes or the Tuxedo services. A transaction encompasses a starting point, a set of program statements, and an end point. A call to the begin() method in the initiator begins the transaction. A transaction is terminated by a call to either commit() or setRollbackOnly(). The terminating calls must be invoked by the initiator. All services invoked between begin() and the terminating calls form part of the transaction. The setTransactionTimeout() function call is used to ensure that service requests are replied to within a specified reasonable time or are terminated abnormally if the reply isn't sent within the specified time. On a successful return from commit(), all changes performed during the transaction are persisted permanently to a data store. The call to setRollbackOnly() is used to return to the initial state without committing any changes performed during the transaction.

The transaction began in WebLogic and is propagated to the Tuxedo domain using the TuxedoConnection object obtained after initiating the transaction with a JTA call begin().

TPNOTRAN Flag

Tuxedo service routines called within the transaction boundary defined by begin and commit/rollback are part of the current transaction. If a particular Tuxedo call must be excluded from a transaction, the corresponding tpcall or tpacall can be called with the flags parameter set to TPNOTRAN. In this case, all operations performed by the called service are excluded from the current transaction and are not affected by the outcome of the current transaction.

Tuxedo Transaction Primitives and JTA

As we saw in Chapter 9, "Processing Transactions with the Java Transaction API," JTA manages the transactions with the following three main interfaces:

• Transaction— This interface is used to enlist resources, synchronize registration, and perform transaction completion and status query operations.

• TransactionManager— This interface is used by the application server to communicate to the transaction manager for transaction boundary demarcation on behalf of the application.

• UserTransaction— This interface, which is a subset of the TransactionManager interface, offers more control to restrict access to the transaction object.

All JTA transaction primitives have equivalent Tuxedo primitives for outward propagation of transactions. Table 34.5 compares the two sets of primitives.

Table 34.5. JTA Versus Tuxedo

JTA	Tuxedo
begin()	tpbegin()
commit()	tpcommit()
abort()	tpabort()

Additionally, transaction time in JTA can be using setTransactionTimeout(), whereas the tpbegin call takes the timeout value as an argument. Tuxedo also provides a tpgetlev call to determine whether a particular routine is in a transaction that's managed by getStatus() in JTA.

WTC and JMS

WTC provides a bi-directional JMS interface for the J2EE components of WebLogic Server to communicate with the Tuxedo domain. This is accomplished using the tBridge component of the WTC. The components involved in this specific integration are WebLogic JMS and Tuxedo /Q. For more information about setting up Tuxedo /Q, refer to http://edocs.bea.com/tuxedo/tux81/qgd/qadm.htm. JMS messages can be text messages, byte messages, or XML-based message streams. The messages are transferred to the Tuxedo environment to be executed by a Tuxedo service or targeted to a /Q environment.

The tBridge section of the WTCServer configuration element in the config.xml file manages the connectivity of the tBridge component into the Tuxedo environment. No additional application programming is involved in establishing the connection and forwarding the requests. The tBridge connector does not support the ObjectMessage, MapMessage, and StreamMessage types.

tBridge Configuration

The tBridge component establishes a one-way data connection between instances of a JMS queue and a Tuxedo /Q or a JMS queue and a Tuxedo service. A WTCtBridgeRedirect MBean represents this connection.

The WTCtBridgeGlobal and WTCtBridgeRedirect MBeans of a WTCServer MBean are configured and deployed to a target server to establish the connectivity between the domains. The connections established are of the following types:

• JmsQ2TuxQ

• TuxQ2JmsQ

• JmsQ2TuxS

JMSQ2TuxQ

This configuration reads messages from a given JMS queue and forwards them to the specified Tuxedo /Q. The following XML code snippet configures the JMSQ2TuxQ:

The tBridge provides simple translation between XML and FML32 to provide connectivity to existing Tuxedo systems. This simple translation is controlled by the TranslateFML element. The valid values for this element are NO and FLAT. The BytesMessage from JMS is automatically converted to a TypedCARRAY, and TranslateFML set to NO converts the TextMessage to TypedString. When TranslateFML is set to FLAT, theTextMessage from JMS is converted to a TypedFML32 buffer.

TuxQ2JMSQ

The following configuration reads messages from a given Tuxedo queue and forwards the messages to the specified JMS queue. The following XML snippet configures TuxQ2JMSQ:

All message types defined in Table 34.1 are supported in this message-forwarding mechanism except the VIEW message type. TypedString, TypedFML, TypedFML32, and TypedXML are converted to TextMessagewhen they're to be processed by the receiving JMS queue. The TranslateFML attribute controls the data translation when required using the built-in tBridge converter. When set to FLAT, data is converted from FML to XML by the tBridge. The message buffer is converted using the field-by-field values without knowledge of the message hierarchy.

JMSQ2TuxS

This configuration reads from a given JMS queue, synchronously calls the specified Tuxedo service, and places the reply back onto a specified JMS queue. The following XML configuration snippet configuresJMSQ2TuxS:

The supported JMS message types are BytesMessage and TextMessage, which are converted to TypedCARRAY and TypedString or TypedFML32, respectively. The TextMessage from JMS is converted to a String buffer or a FML buffer based on the TranslateFML parameter defined in the configuration. In the preceding case, the message in XML format is converted to a corresponding FML32 buffer and placed in the Tuxedo domain queue to be processed by the AUTH_CC Tuxedo service. The reply is then translated from FML32 to XML and placed in wlsunleashed.jms.Tux2JmsQueue.

WTC Security

Remote Tuxedo domains can be controlled to access the services defined and advertised in the WLS domain using the access control lists (ACLs). There are distinct elements in the WTCServer MBean that controls the inbound requests into WTC and outbound requests into the remote Tuxedo domains. The AclPolicy element controls the inbound policy from a remote Tuxedo domain and the CredentialPolicy element defines the outbound policy. The valid values for AclPolicy and CredentialPolicy are

• LOCAL— When AclPolicy is set to LOCAL, local service access does not depend on the value of the credential policy. When the remote Tuxedo domain's credential policy is set to LOCAL, the result depends on the user credentials of the caller.

• GLOBAL— When AclPolicy is set to GLOBAL, local service access depends on the value of the credential policy. When the remote domain credential policy is set to GLOBAL, then the request has the credentials of the caller.

These parameters can be configured using the WebLogic Console as shown in Figure 34.8.

Figure 34.8. Remote Tuxedo domain security configuration.

Similarly, the security parameter in the WTCLocalTuxDom is used to authenticate incoming connections from remote domains and outgoing connections requested by local domains. The valid values for this parameter are

• NONE— Incoming connections from the remote domain are not authenticated.

• Application Password— Incoming connections from remote domains are authenticated using the application password defined in the WTCPassword MBean.

• Domain Password— In this case, connections between the local and remote domains are authenticated using password pairs defined in the WTCPassword MBean.

These parameters also can be configured using the WebLogic Console, as shown in Figure 34.9.

Figure 34.9. Local Tuxedo access point security configuration.

NOTE

The security parameter of the WTC domain and the remote Tuxedo domain should match for a successful connection.

WTC and WebLogic Clusters

There are certain limitations with WTC when working with WebLogic clusters. All the servers in the cluster must have a configured WebLogic Tuxedo Connector. The WTC binding is not automatically propagated across the servers in the cluster. Additionally, all instances should have the same services advertised using the WTCImport MBean. The J2EE components using the WTC should also be deployed on all the servers of the cluster. Inbound RMI/IIOP and outbound CORBA are not supported in clusters.

Additionally, WTC allows for an unlimited number of backup domains for a given WTC service. It provides a domain-level failover mechanism that transfers to alternative remote domains when a primary remote domain fails. It also provides failback to the primary remote domain when it's restored.

WTC and Workflow Processes

WTC provides the essential infrastructure for integrating the business flows defined using the WebLogic Process Integrator (WLI) to use the services defined in a remote Tuxedo domain. The integration components are provided by the tBridge interface.

WLI uses the JATMI to invoke the remote Tuxedo services. eLink adapter services can be invoked from WLI-defined business components. The buffers used to transfer messages for the business call are based on FML32. WLI exception handlers can be defined separately to process exceptions.

Synchronous Integration

The messages from WLI to the remote Tuxedo domain can be sent synchronously or asynchronously. The messages from WLI are pushed to the JMS queue, which uses the tBridge interface to invoke the target Tuxedo service. The message is converted to/from XML/FML using the built-in translator. The response is picked up by the business operation from the response queue.

Asynchronous Integration

WLI and Tuxedo /Q provide the infrastructure for asynchronous message integration. Asynchronous integration is bi-directional. There is a 1:1 relationship between JMS queue and /Q. WLI writes the message to the JMS queue, which invokes the target /Q based on the message. The reverse integration is achieved by the requests from the Tuxedo /Q to the corresponding JMS queue. The workflow defined in WLI waits for the message on the JMS queue.

Now, we'll move to the CORBA integration mechanisms available in a WebLogic Server environment. The first half of the discussion covers WebLogic RMI over IIOP, which is the enabling technology for CORBA integration.