WebTJCA API

This chapter describes the WebTJCA API, which implements CCI to develop outbound communication.

1. CCI

CCI defines a client API to use resource adapters. Users can use CCI to create application code that is compatible with various resource adapters.

A JCA resource adapter is not required to support CCI. Using CCI to develop an application is optional, and an application can be developed by using the company’s own specification.

The followings are the interfaces required by the JCA specification. WebTJCA can use the following CCIs to implement an application.

  • Connection interfaces to be created in applications

    • javax.resource.cci.connectionFactory

    • javax.resource.cci.Connection

    • javax.resource.cci.ConnectionSpec

    • javax.resource.cci.LocalTransaction

  • Interfaces for connectivity with an EIS

    • javax.resource.cci.Interaction

    • javax.resource.cci.InteractionSpec

  • Message listener interface to be implemented in the message-driven bean within the inflow structure

    • javax.resource.cci.MessageListener

  • Interfaces for exchanging data with an EIS

    • javax.resource.cci.Record

    • javax.resource.cci.MappedRecord

    • javax.resource.cci.IndexedRecord

    • javax.resource.cci.RecordFactory

    • javax.resource.cci.Streamable

    • javax.resource.cci.ResultSet

    • java.sql.ResultSetMetaData

  • Meta interfaces that provide basic information about resource adapter implementation and EIS connection.

    • javax.resource.cci.ConnectionMetaData

    • javax.resource.cci.ResourceAdapterMetaData

    • javax.resource.cci.ResultSetInfo

  • Other interfaces

    • javax.resource.ResourceException

    • javax.resource.cci.ResourceWarning

Refer to the JDK JavaDoc for methods of interfaces.

1.1. Connection APIs

After a resource adapter is deployed, the user can refer to a ConnectionFactory by using JNDI and then create a connection using the ConnectionFactory. A new connection is created or an existing connection is returned by calling getConnection().

The following is an example of using a WebTJCA connection.

ConnectionFactory connFactory = (ConnectionFactory)ctx.lookup("TmaxConnector");
Connection conn = connFactory.getConnection();

1.2. APIs for Service Requests

An interaction interface used to request a service is created in the connection interface, and the service to be called is defined in the class that implements InteractionSpec. Since the interface for creating InteractionSpec is not defined in the specification, WebTJCA uses TmaxInteractionSpecImpl. WebTJCA only provides synchronous calls.

The following is an example of sending a service request.

Interaction action = conn.createInteraction();
TmaxInteractionSpecImpl aspec = new TmaxInteractionSpecImpl();
aspec.setSvcName("TOUPPER");
aspec.setAction(InteractionSpec.SYNC_SEND_RECEIVE);

RecordFactory recordFactory = connFactory.getRecordFactory();
MappedRecord sndBuf = recordFactory.createMappedRecord(null);
sndBuf.put("$String","abc");
MappedRecord rcvBuf = recordFactory.createMappedRecord(null);

if( action.execute(aspec, sndBuf, rcvBuf) )
{
    String result = (String)rcvBuf.get("$String");
    System.out.println(result);
}

1.3. APIs for Recording Data

WebTJCA supports string, CArray, and FDL data types.

Retrieve a RecordFactory from ConnectionFactory by using the getRecordFactory() method, and create a data object by using createMappedRecord() to enter data.

The following is an example of creating a RecordFactory.

RecordFactory recordFactory = connFactory.getRecordFactory();
MappedRecord sndBuf = recordFactory.createMappedRecord(null);

The following describes different method usages by data type:

  • String

    Use the put method of MappedRecord to specify this data type. When "$String" is set to the key of the put method, the value is regarded as a string so the string type of the message is sent to Tmax. When "$String" is entered for the get function, the stored string object is returned. The following is an example of representing data as a string type.

    MappedRecord sndBuf = recordFactory.createMappedRecord(null);
sndBuf.put("$String","abc");

  • CArray

    Use the put method of MappedRecord to specify this data type. When "$CArray" is set to the key of the put method, the value is regarded as a set of bytes so the CArray type of message is sent to Tmax. When "$String" is entered for the get function, the stored bytes are returned. The following is an example of representing data as a CArray type.

    MappedRecord sndBuf = recordFactory.createMappedRecord(null);
sndBuf.put("$CArray",new byte[]{0,1,2});

  • FDL

    Use the put method of MappedRecord to specify this data type. When the key specified in FDL is set to the key of the put method, the value is regarded as a field data type so the FDL type message is sent to Tmax. Store the field key and data in pairs by using the put method. The following is an example of representing data as a FDL type.

    MappedRecord sndBuf = recordFactory.createMappedRecord(null);
sndBuf.put("ID","tmax001");
sndBuf.put("PASS","abcd");
sndBuf.put("AGE",16);

    When using the put method to refer to stored data, the get method is used. The return object of the get method returns com.tmax.connector.cci.TmaxFdlRecord, which implements the IndexedRecord that contains the field value. The field value can be referred to by using the get(int index) method of IndexedRecord.

    IndexedRecord field = sndBuf.get("ID");
String id = field.get(0);

2. Transactions

2.1. XA Transactions

WebTJCA supports XA transactions. In ra.xml, <support-xa> must be set to true and <transaction-support> must be set to the XA transaction.

XA-enabled entities automatically participate in a global transaction when getConnection is executed. If the transaction is committed or rolled back by an application, the transaction notifies Tmax of its prepared or committed status.

To process the recovery, xid mapping file related information must be specified in <outbound-resourceadapter><connection-definition>. If this file does not exist, the WAS cannot be restarted.

To execute an XA transaction, configure JEUSGW of Tmax and then access the port.

2.2. Local Transactions

To process a local transaction, the getLocalTransaction method must be used in a connection. With the configuration, the local transaction is automatically enabled in the web application.

The following is an example of using a local transaction.

ConnectionFactory connFactory = (ConnectionFactory)ctx.lookup("TmaxConnector");
Connection conn = connFactory.getConnection();
conn.getLocalTransaction().begin();
...

conn.getLocalTransaction().commit();

Local transactions require access through the default port of Tmax. Local transactions are not available through JAVAGW.

3. Logging

Logs generated while using a resource adapter are written based on the log file and log level configured using ra.xml. Connection logs are controlled by the log-related configuration defined under <outbound-resourceadapter> <connection-definition>. For more information, refer to Configuring ra.xml.

4. Asynchronous Request and Interactive Communication

Since the current CCI specification does not support the asynchronous requests and interactive communication features provided by Tmax, you must use the existing WebT API as shown below.

Asynchronous requests and interactive communication can be implemented using WebtRemoteService() or WebtDialogueService(), by obtaining a WebtConnection from a Connection instance.

The following is an example of implementing asynchronous request handling.

ConnectionFactory connFactory = (ConnectionFactory)ctx.lookup("TmaxConnector");
Connection conn = connFactory.getConnection();
WebtConnection webtConn = ((TmaxConnectionImpl)conn).getInConnection();
WebtRemoteService svc = new WebtRemoteService("TOUPPER", webtConn);
int cd = svc.tpacall(sendBuf);
rcvBuf = svc.tpgetrply(cd);
conn.close();

The following is an example of implementing interactive communication.

ConnectionFactory connFactory = (ConnectionFactory)ctx.lookup("TmaxConnector");
Connection conn = connFactory.getConnection();
WebtConnection webtConn = ((TmaxConnectionImpl)conn).getInConnection();
WebtDialogueService svc = new WebtDialogueService("TOUPPER_CONV", webtConn);
svc.tpconnect(sndbuf..
...
conn.close();