Programming Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Oracle Tuxedo JCA Adapter Programming Guide

This chapter contains the following topics:

 


Overview

The Oracle Tuxedo JCA Adapter supports both standard JEE Connector Architecture Common Client Interface (CCI) and Oracle Tuxedo Java Application-To-Monitor Interface (JATMI). Both interfaces allow client applications to access services located in remote Oracle Tuxedo application domains. The Oracle Tuxedo JCA Adapter supports transparent routing and load balancing internally. Requests are load-balanced and routed to different remote Oracle Tuxedo application domains that provide the same service.

Prerequisites

Developing an Oracle Tuxedo JCA Adapter application requires the following prerequisites:

Common Development Tasks

Developing an application for the Oracle Tuxedo JCA Adapter requires the following steps:

  1. Identify remote Oracle Tuxedo resources needed
  2. Configure the resource deployment descriptor
  3. Configure the Oracle Tuxedo JCA Adapter
  4. Create resource archive
  5. Deploy the Oracle Tuxedo JCA Adapter
Note: These steps can be done independent of application development, but must be completed before running the client application. For more information, see the Oracle Tuxedo JCA Adapter Users Guide.

 


Using Connection Instance and Connection Factory

All client applications are required to lookup the Connection Factory for the Oracle Tuxedo JCA Adapter in the JNDI tree to retrieve a connection instance. The exact lookup string may differ depending on the configuration.

Different application servers may use different implementations to provide this information to the Oracle JCA Adapter. For example, Oracle WebLogic server uses the weblogic-ra.xml file (using the <jndi-name> XML tag) to provide this information as shown in Listing 1.

IBM WebSphere configures this information through the administration console using the "JNDI name" field of the "J2C Connection Factory" page.

Listing 1 Oracle WebLogic Server Connector
<weblogic-connector
  xmlns=http://www.bea.com/ns/weblogic/90>
  <jndi-name>eis/TuxedoConnector</jndi-name>
  ...
  <outbound-resource-adapter>
    <connection-definition-group>
<connection-factory-interface>javax.resource.cci.ConnectionFactory</connection-factory-interface>
       <connection-instance>
          <jndi-name>eis/TuxedoConnectionFactory</jndi-name>
        </connection-instance>
      </connection-definition-group>
    <outbound-resource-adapter>
</weblogic-connector>

Listing 2 shows a Connection Factory lookup and Connection instance code example.

Listing 2 Connection Factory Lookup/Connection Instance Code Example
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

...

import javax.resource.cci.ConnectionFactory;
import javax.resource.cci.Connection;

...

Context ctx;
ConnectionFactory cf;
Connection c;

...

ctx = new InitialContext();
cf = ctx.lookup("eis/TuxedoConnectionFactory");
c = cf.getConnection();

...

The "ctx.lookup()" call uses the string configured in "jndi-name".

 


Using the DMConfigChecker Utility

The DMConfigChecker utility is used to encrypt configuration file passwords. It checks the Oracle Tuxedo JCA Adapter configuration file syntax and replaces all the unencrypted password elements with the encrypted password. If necessary, this utility can also generate a key file which is used to encrypt/decrypt the passwords.

For more information, see the Oracle Tuxedo JCA Adapter Command Reference.

 


Developing an Oracle Tuxedo JCA Adapter Client Application

For client applications, the Oracle Tuxedo JCA Adapter implements the necessary connection creation, session authentication, data privacy, data transformation, routing/load balancing, and transaction processes. This makes it easier, consistent, and transparent for an Oracle Tuxedo JCA Adapter client to access Oracle Tuxedo services.

Not all application servers run client programs in the same manner; they may have their own toolset and implementation methodology. In general, after you develop the client application, you must do the following steps to run client application server programs:

  1. Build the client application
  2. Configure the client application
  3. Deploy the client application
  4. Run the client application
Note: Refer to your target Application Server documentation for detailed information on how to build, configure, deploy, and run client applications.

This section contains the following topics:

CCI Client Programming

Client applications can access Oracle Tuxedo services using the JEE Connector Architecture Common Client Interface (CCI).

To develop a CCI-based Tuxedo JCA Adapter client application, you must do the following steps:

  1. Create a new interaction and specification instance.
  2. Set the imported Oracle Tuxedo service name and call.
  3. Create and input a new Oracle Tuxedo Typed Buffer data record instance.
  4. Execute service requests.
  5. Release resources.
  6. Retrieve data record output reply

The code examples in this section perform service calls to an Oracle Tuxedo service. The service name is "TOUPPER" and requires configuration. For more information, see Configuration File Examples. The "TOUPPER" service uses a STRING Typed Buffer for input and output.

To create a new interaction instance, the client application must place a call to the Connection. The interaction between client applications (javax.resource.cci.Interaction) and Oracle Tuxedo services must be customized using the interaction specification (javax.resource.cci.InteractionSpec) as shown in Listing 3.

Listing 3 Create a New Interaction Instance and Specification
Interaction                     ix;
TuxedoInteractionSpec ixspec;

...

ix = c.reateInteraction()
ixspec = new TuxedoInteractionSpec();

You must import the following:

Listing 4 shows a client application synchronously invoking the "TOUPPER" service.

Listing 4 CCI Client Application Invoking TOUPPER Service
ixspec.setFunctionName("TOUPPER");
ixspec.setInteractionVerb(InteractionSpec.SYNC_SEND_RECEIVE);

The input data sent must use an Oracle Tuxedo Typed Buffer.

Listing 5 shows the "TOUPPER" service using a STRING buffer type for input and output.

Listing 5 TOUPPER" Service Using a STRING Buffer Type
TuxedoStringRecord  inRec;
TuxedoStringRecord outRec;

...

inRec = new TuxedoStringRecord();
outRec = new TuxedoStringRecord();
inRec.setRecordName("MyInputData");
outRec.setRecordName("MyOutputData");

inRec.setString(string_to_convert)

Listing 6 shows the actual "TOUPPER" service request, resource release, and reply data retrieval.

Listing 6 Service Request, Release Resources, and Output Data Retrieval
ix.execute(ixspec, inRec, outRec);

ix.close();
c.close();

String returned_data = outRec.getString();

To compile the Java code, the client application must import the following packages.

Listing 7 shows a CCI client application program example.

Listing 7 CCI Client Application Program Example
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.ejb.CreateException;

import javax.resource.cci.ConnectionFactory;
import javax.resource.cci.Connection;
import javax.resource.cci.Interaction;
import javax.resource.cci.Interactionspec;
import javax.resource.ResourceException;

import weblogic.wtc.jatmi.TPException;
import weblogic.wtc.jatmi.TPReplyException;

import com.oracle.tuxedo.adapter.TuxedoReplyException;
import com.oracle.tuxedo.adapter.cci.TuxedoStringRecord;
import com.oracle.tuxedo.adapter.cci.TuxedoInteractionSpec;

...

public String Toupper(String string_to_convert) throws TPException, TuxedoReplyException
{
  Context ctx;
  ConnectionFactory cf;
  Connection c;
  Interaction ix;
  TuxedoStringRecord inRec;
  TuxedoStringRecord outRec;
  TuxedoInteractionSpec ixspec;

  try {
    ctx = new InitialContext();
    cf = ctx.lookup("eis/TuxedoConnectionFactory");
    c = cf.getConnection();

    ix = c.createInteraction();
    ixspec = new TuxedoInteractionSpec();
    ixspec.setFunctionName("TOUPPER");
    ixspec.setInteractionVerb(InteractionSpec.SYNC_SEND_RECEIVE);

    inRec = new TuxedoStringRecord();
    outRec = new TuxdeoStringRecord();
    inRec.setRecordName("MyInputData");
    outRec.setRecordMane("MyOutputData");

    outRec.setString(string_to_convert);
    ix.execute(ixspec, inRec, outRec);

    ix.close();
    c.close();

    String returned_data = outRec.getString();
    return returned_data;
  }
  catch (NamingException ne) {
    throw new TPException(TPException.TPESYSTEM,
                                        "Could not get TuxedoConnectionFactory");
  }
  catch (ResourceException re) {
    throw new TPException(TPException.TPESYSTEM,
                                 "ResourceException occurred, reason: " + re);
  }
}

Transaction Client Programming

The Oracle JCA Adapter supports CCI-managed transaction client applications. The type of transaction depends largely on the transaction level (XA transactions or local transactions) configured in the Oracle Tuxedo JCA Adapter deployment descriptor. For more information, see the Oracle Tuxedo JCA Adapter Users Guide.

CCI-Managed XA Client Programming

To develop a VIEW buffer type-based CCI-managed XA client application, you must do the following steps:

  1. Compile VIEW definition using viewj32 compiler.
  2. Get user transaction, set transaction timeout, and start transaction.
  3. Create new interaction and specification instance.
  4. Set the imported Oracle Tuxedo service name.
  5. Set the style of call.
  6. Instantiate and initialize VIEW32 object.
  7. Create new Oracle Tuxedo Typed Buffer data record instance.
  8. Execute the service request.
  9. Get the reply.
  10. Commit the transaction.
  11. Release the resources.
  12. Retrieve the output data record reply.

The code examples in this section perform service calls to an Oracle Tuxedo service. The service name is TOUPPER_V32 and requires configuration. For more information, see Configuration File Examples. The "TOUPPER_32" service requires a VIEW32 Typed Buffer for input and output.

Note: The equivalent of VIEW32 Typed Buffer in Tuxedo JCA Adapter is TuxedoView32Record. In the following examples VIEW32 view is called "View32". The java code is generated using the viewj32 compiler.
Note: For more information, see Managing Typed Buffers in Programming An Oracle Tuxedo ATMI Application Using C and the Oracle Tuxedo JCA Adapter Command Reference Guide for viewj and viewj32 information.

Listing 8 shows a VIEW32 definition file example.

Listing 8 VIEW32 Definition File Example
VIEW View32
short TEST_SHORT - 1 - - 0
string TEST_STRING - 1 - 100 -

Compile using the following viewj32 utility command:

java -classpath %CLASSPATH% weblogic.wtc.jatmi.viewj32 tuxedo.test.simapp View32

This command creates a "View32.java" Java class file (package name "tuxedo.test.simpapp") in the current working directory.

Listing 9 shows how to create and start a user transaction. The transaction will timeout after 300 seconds.

Listing 9 Create and Start a User Transaction
UserTransaction utx;

...

utx = (UserTransaction)ctx.lookup("java:comp/UserTransaction");
utx.setTransactionTimeout(300);
utx.begin();

To create new interaction instance, the client application must place a call to the Connection. The interaction between client applications (javax.resource.cci.Interaction) and Oracle Tuxedo services must be customized using the interaction specification (javax.resource.cci.InteractionSpec) as shown in Listing 10.

Listing 10 Create a New Interaction Instance and Specification
Interaction                     ix;
TuxedoInteractionSpec ixspec;

...

ix = c.reateInteraction()
ixspec = new TuxedoInteractionSpec();

You must import the following:

Listing 11 shows a client application invoking the "TOUPPER_32" service using asynchronous interaction.

Listing 11 CCI Transaction Client Application Invoking TOUPPER Service
ixspec.setFunctionName("TOUPPER_V32");
ixspec.setInteractionVerb(InteractionSpec.SYNC_SEND);

The input data sent to Oracle Tuxedo must use an Oracle Tuxedo Typed Buffer.

Listing 12 shows the "TOUPPER_32" service using a VIEW32 Typed Buffer for input and output.

Listing 12 TOUPPER_32 Service Using a VIEW32 Buffer Type
View32                         myData;
TuxedoView32Record inRec;

...

myData = new View32();
myData.setTEST_SHORT((short)4);
myData.setTEST_STRING(string_to_convert);

inRec = new TuxedoView32Record(myData);
inRec.setRecordName("MyInputData");

Listing 13 shows the actual "TOUPPER_32" service request, resource release, and reply data retrieval.

Listing 13 Service Request, Release Resources, and Output Data Retrieval
TuxedoView32Record outRec;

...

ix.execute(ixspec, inRec);
ixspec.setInteractionVerb(InteractionSpec.SYNC_RECEIVE);
outRec = (TuxedoView32Record)ix.execute(ixspec, inRec);

utx.commit();
ix.close();
c.close();

View32 myDataBack = (View32)outRec.getView32();
String returned_data = myDataBack.getTEST_STRING();

To compile the Java code, the client application must import the following packages:

Listing 14 shows a transaction client application program example.

Listing 14 Transaction Client Application Program Example
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.ejb.CreateException;

import javax.resource.cci.ConnectionFactory;
import javax.resource.cci.Connection;
import javax.resource.cci.Interaction;
import javax.resource.cci.Interactionspec;
import javax.resource.ResourceException;

import weblogic.wtc.jatmi.TPException;
import weblogic.wtc.jatmi.TPReplyException;

import com.oracle.tuxedo.adapter.TuxedoReplyException;
import com.oracle.tuxedo.adapter.cci.TuxedoView32Record;
import com.oracle.tuxedo.adapter.cci.TuxedoInteractionSpec;

import tuxedo.test.simpapp.View32;

...

private void cleanup(UserTransaction utx, Interaction ix, Connection c)
{
  try {
     if (utx != null) utx.rollback();
     if (ix != null) ix.close();
     if (c != null) c.close();
  }
  catch (Exception e) {
    /* ignore */
  }
}

public String Toupper(String string_to_convert) throws TPException, TuxedoReplyException
{
  Context ctx;
  ConnectionFactory cf;
  Connection c;
  UserTransaction utx;
  View32 myData;
  View32 myDataBack;
  Interaction ix;
  TuxedoView32Record inRec;
  TuxedoView32Record outRec;
  InteractionSpec ixspec;

  try {
    ctx = new InitialContext();
    cf = ctx.lookup("eis/TuxedoConnectionFactory");
    c = cf.getConnection();
    utx = (UserTransaction)ctx.lookup("java:comp/UserTransaction");
    utx.setTransactionTimeout(300);
    utx.begin();

    ix = c.createInteraction();
    ixspec = new TuxedoInteractionSpec();
    ixspec.setFunctionName("TOUPPER_V32");
    ixspec.setInteractionVerb(InteractionSpec.SYNC_SEND);

    myData = new View32();
    myData.setTEST_SHORT((short)4);
    myData.setTEST_STRING(string_to_convert);

    inRec = new TuxedoView32Record(myData);
    inRec.setRecordName("MyInputData");

    ix.execute(ixspec, inRec);
    ixspec.setInteractionVerb(InteractionSpec.SYNC_RECEIVE);
    outRec = (TuxedoView32Record)ix.execute(ixspec, inRec);

    utx.commit();
    ix.close();
    c.close();

    myDataBack = (View32)outRec.getView32();
    String returned_data = myDataBack.getTEST_STRING();
    return returned_data;
  }
  catch (NamingException ne) {
    cleanup(utx, ix, c);
    throw new TPException(TPException.TPESYSTEM,
                                "Could not get TuxedoConnectionFactory");
  }
  catch (ResourceException re) {
    cleanup(utx, ix, c);
    throw new TPException(TPException.TPESYSTEM,
                                            "ResourceException occurred, reason: " + re);
  }
  catch (javax.transaction.RollbackException rbe) {
    cleanup(utx, ix, c);
    throw new TPException(TPException.TPETRAN, "Exception: " + rbe);
  }
  catch (javax.transaction.NotSuppotedException hre) {
    cleanup(utx, ix, c);
    throw new TPException(TPException.TPETRAN, "Exception: " + nse);
  }
  catch (javax.transaction.HeuristicRollbackException hre) {
    cleanup(utx, ix, c);
    throw new TPException(TPException.TPETRAN, "Exception: " + hre);
  }
  catch (javax.transaction.HeuristicMixException hme) {
    cleanup(utx, ix, c);
    throw new TPException(TPException.TPETRAN, "Exception: " + hme);
  }
  catch (javax.transaction.SystemException se) {
    cleanup(utx, ix, c);
    throw new TPException(TPException.TPETRAN, "Exception: " + se);
  }
}

CCI-Managed Local Transaction Programming

The Oracle Tuxedo JCA Adapter supports local managed transaction client applications using CCI. The transaction requires an Oracle Tuxedo JCA Adapter specific extension in order to set per transaction timeouts.

To develop a synchronous CCI-based Tuxedo JCA Adapter local managed transaction client program using a VIEW32 Typed Buffer, you must do the following steps:

  1. Create a new Local Transaction instance.
  2. Create a new interaction and specification instance.
  3. Set the imported Oracle Tuxedo service name.
  4. Set the call style.
  5. Start Local Transaction.
  6. Create a new Oracle Tuxedo Typed Buffer data record instance.
  7. Send the input data to the data record.
  8. Execute the service request.
  9. Commit Local Transaction.
  10. Release the resources.
  11. Retrieve output data record reply.

The code examples in this section perform service calls to an Oracle Tuxedo service. The service name is TOUPPER and requires configuration. For more information, see Configuration File Examples. The "TOUPPER" service requires a STRING Typed Buffer for input and output.

Listing 15 shows how create a new Oracle Tuxedo JCA Adapter Local Transaction instance from the Oracle Tuxedo Connection (com.oracle.tuxedo.adapter.cci.TuxedoJCALocalTransaction).

Listing 15 Create a New Local Transaction Instance
TuxedoJCALocalTransaction ltx;

...

ltx = (TuxedoJCALocalTransaction)c.getLocalTransaction();

To create new interaction instance, the client application must place a call to the Connection. The interaction between client applications (javax.resource.cci.Interaction) and Oracle Tuxedo services must be customized using the interaction specification (javax.resource.cci.InteractionSpec) as shown in Listing 16.

Listing 16 Create a New Interaction and Specification
Interaction                     ix;
TuxedoInteractionSpec ixspec;

...

ix = c.reateInteraction()
ixspec = new TuxedoInteractionSpec();

Listing 17 shows how to create and start a managed local transaction. The transaction will timeout after 15 seconds.

Note: This is an Oracle Tuxedo JCA Adapter specific implementation and is not part of the standard CCI Local Transaction interface.
Listing 17 Create and Start a Local Transaction
ltx.begin(15);

You must import the following:

Listing 18 shows the client application synchronously using the "TOUPPER" service.

Listing 18 Local Transaction Client Application Invoking TOUPPER Service
ixspec.setFunctionName("TOUPPER");
ixspec.setInteractionVerb(InteractionSpec.SYNC_SEND_RECEIVE);

The input data sent to Oracle Tuxedo must use an Oracle Tuxedo Typed Buffer.

Listing 19 shows the "TOUPPER" service using a STRING Typed Buffer for input and output.

Listing 19 TOUPPER Service Using a STRING Typed Buffer
TuxedoStringRecord  inRec;
TuxedoStringRecord outRec;

...

inRec = new TuxedoStringRecord();
outRec = new TuxedoStringRecord();
inRec.setRecordName("MyInputData");
outRec.setRecordName("MyOutputData");
inRec.setString(string_to_convert);

Listing 20 shows the actual "TOUPPER" service request, resource release, and reply data retrieval.

Listing 20 Service Request, Release Resources, and Output Data Retrieval
ix.execute(ixspec, inRec, outRec);

if (outRec.getTperrno() == 0) {
  ltx.commit();
}
else {
  ltx.rollback();
}
ltx = null;

ix.close();
c.close();

String returned_data = outRec.getString();

To successfully compile the Java code, the client application must import the following packages.

Listing 21 shows a local transaction client application program example.

Listing 21 Local Transaction Client Application Program Example
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.ejb.CreateException;

import javax.resource.cci.ConnectionFactory;
import javax.resource.cci.Connection;
import javax.resource.cci.Interaction;
import javax.resource.cci.Interactionspec;
import javax.resource.ResourceException;

import weblogic.wtc.jatmi.TPException;
import weblogic.wtc.jatmi.TPReplyException;

import com.oracle.tuxedo.adapter.TuxedoReplyException;
import com.oracle.tuxedo.adapter.cci.TuxedoView32Record;
import com.oracle.tuxedo.adapter.cci.TuxedoInteractionSpec;
import com.oracle.tuxedo.adapter.cci.TuxedoJCALocalTransaction;

...

public String Toupper(String string_to_convert) throws TPException, TuxedoReplyException
{
  Context ctx;
  ConnectionFactory cf;
  Connection c = null;
  TuxedoJCALocalTransaction ltx = null;
  Interaction ix = null;
  TuxedoStringRecord inRec;
  TuxedoStringRecord outRec;
  InteractionSpec ixspec;

  try {
    ctx = new InitialContext();
    cf = ctx.lookup("eis/TuxedoConnectionFactory");
    c = cf.getConnection();
    ltx = (TuxedoJCALocalTransaction)c.getLocalTransaction();

    ix = c.createInteraction();
    ixspec = new TuxedoInteractionSpec();
    ixspec.setFunctionName("TOUPPER");
    ixspec.setInteractionVerb(InteractionSpec.SYNC_SEND_RECEIVE);
    ltx.begin(15);

    inRec = new TuxedoStringRecord();
    outRec = new TuxedoStringRecord();
    inRec.setRecordName("MyInputData");
    outRec.setRecordName("MyOutputData");
    inRec.setString(string_to_convert);

    ix.execute(ixspec, inRec, outRec);

    if (outRec.getTperrno() == 0) {
      ltx.commit();
    }
    else {
      ltx.rollback();
    }
    ix.close();
    c.close();

    String returned_data = outRec.getString();
    return returned_data;
  }
  catch (NamingException ne) {
    throw new TPException(TPException.TPESYSTEM,
                                    "Could not get TuxedoConnectionFactory");
  }
  catch (ResourceException re) {
    if (ltx != null) {
      try {
        ltx.rollback();
      }
      catch (ResourceException xre) {
        /* ignore it */
      }
    }
      try {
       if (ix != null) ix.close();
       if (c != null) c.close();
    }
    catch (Exception e) {
       /* ignore it */
    }
    throw new TPException(TPException.TPESYSTEM,
                                            "ResourceException occurred, reason: " + re);
  }
}

JATMI Client Programming

Client applications can access an Oracle Tuxedo service using the Java Application To Monitor Interface (JATMI). JATMI is a straight Java implementation of the Oracle Tuxedo ATMI interface.

To develop a JATMI-based Tuxedo JCA Adapter client application, you must do the following steps:

  1. Create a new interaction instance
  2. Create and input a new JATMI Typed Buffer data record instance.
  3. Call Oracle Tuxedo service
  4. Retrieve output data record reply
  5. Release resources

The code examples in this section perform service calls to an Oracle Tuxedo service. The service name is TOUPPER and requires configuration. For more information, see Configuration File Examples. The Tuxedo TOUPPER service requires a STRING Typed Buffer for input and output.

To create new interaction instance, the client application must place a call to the Connection. When you use the JATMI interaction extension (com.oracle.tuxedo.adapter.cci.TuxedoInteractionSpec), an interaction specification is not required to customize the interaction between client applications and Oracle Tuxedo services.The JATMI service invocation interface already includes these interaction specifications as shown in Listing 22.

Listing 22 New JATMI Interaction Instance
Interaction                     ix;

...

ix = c.reateInteraction()

The input data must be transported using an Oracle Tuxedo Typed Buffer. Listing 23 shows the "TOUPPER" service using a STRING Typed Buffer for input and output.

Listing 23 TOUPPER" Service Using a STRING Buffer Type
TypedString inData;

...

inData = new TypedString(string_to_convert);

Listing 24 shows the actual "TOUPPER" service request and data retrieval reply.

Listing 24 JATMI Client Application TOUPPER Service Request and Output Data Retrieval
Reply           myRtn;
TypedString outData;

myRtn = ix.tpcall("TOUPPER", inData, 0);
outData= (TypedString)myRtn.getReplyBuffer();
String returned_data = outData.toString()

Listing 25 shows how the resources are released.

Listing 25 JATMI Client Application Resource Release
ix.tpterm();
c.close();

To compile the Java code, the client application must import the following packages.

Listing 26 shows a JATMI client application program example.

Listing 26 JATMI Client Application Program Example
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.ejb.CreateException;

import javax.resource.cci.ConnectionFactory;
import javax.resource.cci.Connection;
import javax.resource.cci.Interaction;
import javax.resource.cci.Interactionspec;
import javax.resource.ResourceException;

import weblogic.wtc.jatmi.TPException;
import weblogic.wtc.jatmi.TPReplyException;
import weblogic.wtc.jatmi.Reply;
import weblogic.wtc.jatmi.TypedString;

import com.oracle.tuxedo.adapter.TuxedoReplyException;
import com.oracle.tuxedo.adapter.cci.TuxedoInteraction;

...

public String Toupper(String string_to_convert) throws TPException, TPReplyException
{
Context ctx;
ConnectionFactory cf;
Connection c;
Interaction ix;
TypedString inData;
TypedString outData;
Reply myRtn;

try {
    ctx = new InitialContext();
    cf = ctx.lookup("eis/TuxedoConnectionFactory");
    c = cf.getConnection();

    ix = c.createInteraction();
    inData = new TypedString(string_to_convert);
    myRtn = ix.tpcall("TOUPPER", inData, 0);
    outData= (TypedString)myRtn.getReplyBuffer();

    String returned_data = outData.toString();

    ix.tpterm();
    c.close()
    return returned_data;
  }
  catch (NamingException ne) {
    throw new TPException(TPException.TPESYSTEM,
                                    "Could not get TuxedoConnectionFactory");
  }
  catch (ResourceException re) {
    throw new TPException(TPException.TPESYSTEM,
                                            "ResourceException occurred, reason: " + re);
  }
}

Inbound EJB Service Programming

You can use the Oracle Tuxedo JCA Adapter to access EJB-based Tuxedo client services. In order for the Oracle Tuxedo JCA Adapter to invoke an EJB, the EJB must use the weblogic.wtc.jatmi.TuxedoService interface. This interface defines a single method called service as shown in Listing 27.

Listing 27 EJB Service Single Method
public Reply service(TPServiceInformation svcinfo)
        throws TPException, TPReplyException, RemoteException;

To develop an EJB-based service application using the TuxedoService.service() interface, you must do the following steps:

  1. Retrieve input data and perform task.
  2. Create Typed Buffer for output data.
  3. Setup the output data to be returned to caller.
  4. Configure the EJB deployment descriptor.

The code examples in this section show how to:

The service name is TOLOWER and requires configuration. For more information, see Configuration File Examples. The EJB service uses a STRING Typed Buffer for input and output.

Listing 28 shows an example of how input data is retrieved using TPServiceInformation (shown in Listing 27).

Listing 28 EJB Input Data Retrieved from TPServiceInformation
TypedString data;

...

data = (TypedString)mydata.getServiceData();

The input data is converted to lower case as shown in Listing 29

Listing 29 EJB Input Data Converted to Lower Case
String lowered;

...

lowered = data.toString().toLowerCase();

When the output data is available, it must be wrapped in an Oracle Tuxedo Typed Buffer. Listing 30 shows the how the output data is wrapped using the TypedString Typed Buffer.

Listing 30 EJB Output Data Wrapped in TypedString Typed Buffer
TypedString return_data;

...

return_data = new TypedString(lowered);

The output Typed Buffer is then transported back to the caller (using the TPServiceInformation object) as shown in Listing 31.

Listing 31 EJB Output Typed Buffer Transported to Caller
mydata.setReplyBuffer(return_data);

In order for Tuxedo JCA Adapter to successfully invoke the EJB service, the EJB deployment descriptor must be configured using the following information:

The required prefix (tuxedo.services) and the EJB name (TolowerHome) are configured in the <EXPORT> <SOURCE> element of the Oracle Tuxedo JCA Adapter configuration file as shown in Listing 32.

Listing 32 EJB “TOLOWER”Configuration
<Export name="TOLOWER">
  <RemoteName>TOLOWER</RemoteName>
  <SessionName>session_1</SessionName>
  <Type>EJB</Type>
  <Source>tuxedo.services.TolowerHome</Source>
</Export>

To successfully compile the Java code, the client application must import the following packages:

Listing 33 shows an EJB client application program example.

Listing 33 EJB Client Application Program Example
package test.tuxedo.simpserv;

import javax.ejb.CreateException;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

import weblogic.wtc.jatmi.TPException;
import weblogic.wtc.jatmi.TypedString;
import weblogic.wtc.jatmi.Reply;

import com.oracle.tuxedo.adapter.tdom.TPServiceInformation;

...

public Reply service(TPServiceInformation mydata) throws TPException
{
  TypedString data;
  String lowered;
  TypedString returned_data;

  data = (TypedString)mydata.getServiceData();
  lowered = data.toString().toLowerCase();
  returned_data = new TypedString(lowered);

  mydata.setReplyBuffer(return_data);

  return mydata;
}

...

Inbound POJO Service Programming

You can use the Oracle Tuxedo JCA Adapter to access Plain Old Java Object (POJO)-based Tuxedo client services.

In order for the Oracle Tuxedo JCA Adapter to invoke a POJO service, the POJO service must provide a method with same name as the exported name. This method must take two fixed arguments: TPServiceInformation and TPRequestAsyncReply.

To develop an POJO-based service application using the TuxedoService.service() interface, you must do the following steps:

  1. Retrieve input data and perform a task.
  2. Create Typed Buffer for output data.
  3. Setup the output data to be returned to caller.
  4. Inform Tuxedo JCA Adapter POJO handler of success or failure
  5. Configure the POJO deployment descriptor.

The code examples in this section show how to:

The service name is MYTOLOWER and requires configuration. For more information, see Configuration File Examples. The POJO service requires a STRING Typed Buffer for input and output.

Listing 34 shows an example of how input data is retrieved using TPServiceInformation (shown in Listing 27).

Listing 34 POJO Input Data Retrieved from Input TPServiceInformation
TypedString typedstr;

...

data = (TypedString)svcinfo.getServiceData();

The input data is converted to lower case as shown in Listing 35

Listing 35 POJO Input Data Converted into Lower Case
String lower;

...

lower = typedstr.toString().toLowerCase();

When the output data is available, it must be wrapped in an Oracle Tuxedo Typed Buffer. Listing 36 shows the how the output data is wrapped using the TypedString Typed Buffer.

Listing 36 POJO Output Data Wrapped in TypedString Buffer
TypedString return_data;

...

return_data = new TypedString(lower);

The output Typed Buffer is then transported back to the caller (using the TPServiceInformation object) as shown in Listing 31.

Listing 37 POJO Output Typed Buffer Transported to Caller
mydata.setReplyBuffer(return_data);
areply.success(svcinfo);

In order for the Oracle Tuxedo JCA Adapter to successfully invoke a POJO service, the POJO deployment descriptor must be configured. The POJO method name must be configured in the <EXPORT> section of the Oracle Tuxedo JCA Adapter configuration file as shown in Listing 38.

The <SOURCE> element contains the fully qualified class name, and the <SourceLocation> element contains the full path name to the .JAR file that contains the class. The .JAR file must be configured in the CLASSPATH.

Listing 38 POJO "TOLOWER_POJO" Configuration
<Export name="TOLOWER_POJO">
  <RemoteName>TOLOWER_POJO</RemoteName>
  <SessionName>session_1</SessionName>
  <Type>POJO</Type>
  <Source>com.oracle.tuxedo.test.MyTolower</Source>
  <SourceLocation>c:\tuxedo\jca\test\myapp.jar</SourceLocation>
</Export>

To successfully compile the Java code, the client application must import the following packages.

Listing 39 shows a POJO client application program example.

Listing 39 POJO Client Application Program Example
package com.oracle.tuxedo.test;

import javax.ejb.CreateException;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

import weblogic.wtc.jatmi.TPException;
import weblogic.wtc.jatmi.TypedString;
import weblogic.wtc.jatmi.Reply;
import weblogic.wtc.jatmi.TPRequestAsyncReply;

import com.oracle.tuxedo.adapter.tdom.TPServiceInformation;

...

public void TOLOWER_POJO(TPServiceInformation svcinfo, TPRequestAsyncReply areply) throws TPException
{
  TypedString typedstr;
  String lower;
  TypedString returned_data;

  typedstr = (TypedString)svcinfo.getServiceData();
  lower = typedstr.toString().toLowerCase();
  returned_data = new TypedString(lower);

  svcinfo.setReplyBuffer(return_data);
  areply.success(svcinfo);
}

...

 


Configuration File Examples

To run the Oracle Tuxedo JCA Adapter, you must configure the following files:

Oracle Tuxedo JCA Adapter Configuration Examples

The Oracle Tuxedo JCA Adapter configuration file is a formal syntax XML file. The location of this file is configured in the ra.xml file in the resource adapter configuration property. For more information, see the Oracle Tuxedo JCA Adapter Reference Guide.

Listing 40 shows an example ra.xml file snippet that links the configuration file with the Oracle Tuxedo JCA Adapter.

Listing 40 ra.xml File Example
<config-property>
  <config-property-name>dmconfig</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
<config-property-value>c:/myJcaApp/adapter/bdmconfig.xml</config-property-value>
</config-property>

Listing 41 shows an Oracle Tuxedo JCA Adapter DMCONFIG file example that accesses:

The Local Access Point defines the Oracle Tuxedo JCA Adapter listening end point. The Remote Access Point defines the Oracle Tuxedo GWTDOMAIN gateway listening end point.

Listing 41 Oracle Tuxedo JCA Adapter Configuration File
<?xml version="1.0" encoding="UTF-8"?><TuxedoConnector>
  <Resources>
    <ViewFile32Classes>tuxedo.test.simpapp.View32</ViewFile32Classes>
  </Resources>
  <LocalAccessPoint name="JDOM">
    <AccessPointId>JDOM_ID</AccessPointId>
    <NetworkAddress>//localhost:10801</NetworkAddress>
  </LocalAccessPoint>
  <RemoteAccessPoint name="TDOM1">
    <AccessPointId>TDOM1_ID</AccessPointId>
    <NetworkAddress>//localhost:12478</NetworkAddress>
  </RemoteAccessPoint>
  <SessionProfile name="profile_1">
    <Security>NONE</Security>
    <BlockTime>30000</BlockTime>
    <Interoperate>false</Interoperate>
    <ConnectionPolicy>ON_STARTUP</ConnectionPolicy>
    <ACLPolicy>local</ACLPolicy>
    <CredentialPolicy>local</CredentialPolicy>
    <RetryInterval>60</RetryInterval>
    <MaxRetries>1000</MaxRetries>
    <CompressionLimit>1000000</CompressionLimit>
  </SessionProfile>
  <Session name="session_1">
    <LocalAccessPointName>JDOM</LocalAccessPointName>
    <RemoteAccessPointName>TDOM1</RemoteAccessPointName>
    <ProfileName>profile_1</ProfileName>
  </Session>
  <Import name="TOUPPER">
    <RemoteName>TOUPPER</RemoteName>
    <SessionName>session_1</SessionName>
    <LoadBalancing>RoundRobin</LoadBalancing>
  </Import>
  <Import name="TOUPPER_V32">
    <RemoteName>TOUPPER_V32</RemoteName>
    <SessionName>session_1</SessionName>
    <LoadBalancing>RoundRobin</LoadBalancing>
  </Import>
<Export name="TOLOWER">
    <RemoteName>TOLOWER</RemoteName>
    <SessionName>session_1</SessionName>
    <Type>EJB</Type>
    <Source>tuxedo.services.TolowerHome</Source>
  </Export>
  <Export name="TOLOWER_POJO">
    <RemoteName>TOLOWER_POJO</RemoteName>
    <SessionName>session_1</SessionName>
    <Type>POJO</Type>
    <Source>com.oracle.tuxedo.test.MyTolower</Source>
    <SourceLocation>c:\tuxedo\jca\test\MyApp.jar</SourceLocation>
  </Export>
</TuxedoConnector>

Oracle Tuxedo UBBCONFIG and BDMCONFIG Examples

In addition to configuring the Oracle Tuxedo JCA Adapter configuration file, the Oracle Tuxedo UBBCONFIG and BDMCONFIG configuration files must include the Oracle Tuxedo JCA Adapter configuration in order to enable the application.

Listing 42 and Listing 43 show UBBCONFIG and BDMCONFIG file snippet examples required to expose services inside an Oracle Tuxedo Application Domain and inter-domain requests.

Listing 42 UBBCONFIG File Snippet Example
*SERVICES
TOUPPER
TOUPPER_V32
...
Listing 43 BMDCONFIG File Snippet Example
*DM_LOCAL_SERVICES
TOUPPER
TOUPPER_V32
...

*DM_REMOTE_SERVICES
TOLOWER
TOLOWER_POJO

 


See Also


  Back to Top       Previous  Next