Configuring Resource Adapters

We will use Sun's JDBC Connector to illustrate the various issues pertaining to the configuration of resource adapters. Sun's JDBC Connector lets you plug any JDBC-compliant driver into a J2EE Application Server. Its resource adapters serve as pluggable JCA wrappers around the JDBC driver and its connection factories. Please visit http://java.sun.com/products/jdbc/related.html for more information on Sun's JDBC Connector, and on how to download the product.

The downloaded ZIP packages resource adapters that implement the Service Provider Interface (SPI) contracts using the functionality of the DriverManager, the DataSource, the ConnectionPoolDataSource, and the XADataSource classes in a JDBC driver. It also contains resource adapters that implement the CCI contracts using the functionality of the XADataSource. Two versions of each resource adapter are included, one conforming to the Connector v1.0 specification and the other conforming to the more recent Connector v1.5 specification. You have to use the Version 1.0 files (for instance, cci_10_xa.rar) that are supported by WebLogic 8.1.

7.2.1 Generic Settings for the Resource Adapter

The standard ra.xml descriptor file captures general-purpose information about the J2EE connector. In the case of the XA-based JDBC Connector cci_10_xa.rar, the standard XML descriptor includes the following metadata:

XADataSource Resource Adapter Resource adapter wrapping XADatasource implementation of driver Sun Microsystems 1.0 Database 1.0 false ...

In addition, the standard ra.xml descriptor specifies the fully qualified names of the Java interface and implementation class for the resource adapter's connection factory and the connection. The following portion from the ra.xml descriptor lists the Java interfaces and implementation classes used by Sun's XADataSource resource adapter:

com.sun.gjc.cci.CciManagedConnectionFactory javax.resource.cci.ConnectionFactory com.sun.gjc.cci.CciConnectionFactory javax.resource.cci.Connection com.sun.gjc.cci.CciConnection ...

The transaction-support subelement specifies the level of transaction support provided by the resource adapter. As expected, Sun's XADataSource Connector supports distributed transactions, so the ra.xml descriptor includes the following transaction setting:

XATransaction

The ra.xml descriptor file also lists a number of configurable properties that apply to each ManagedConnectionFactory instance. The connection factory then uses these properties to establish managed connections to the underlying EIS resource. Sun's XADataSource resource adapter does support a number of configuration properties: ServerName, PortNumber, User, Password, DatabaseName, InitialPoolSize, MaxPoolSize, ClassName, and many more. These properties mimic the attributes of a JDBC connection pool that supports JTA transactions. For each property, the ra.xml descriptor file defines a name, type, and optional default value:

User java.lang.String scott Password java.lang.String tiger ...

Finally, the ra.xml descriptor file includes information about the authentication mechanism supported by the resource adapter. Typically, a J2EE connector supports two kinds of authentication:

BasicPassword

Authentication based on username-password combinations.

Kerbv5

Authentication based on Kerberos v5 tickets. WebLogic doesn't support resource adapters that provide only Kerbv5-based authentication.

In addition, the ra.xml descriptor file specifies whether the resource adapter supports reauthentication of an existing physical connection. The following portion from the standard ra.xml descriptor file indicates that Sun's XADataSource connector does, in fact, support BasicPassword authentication, but doesn't support reauthentication of existing connections to the EIS resource:

... BasicPassword javax.resource.spi.security.PasswordCredential false ...

7.2.2 Support for Transaction Levels

The JCA framework works in coordination with WebLogic's transaction manager to provide robust support for distributed transactions. As mentioned earlier, WebLogic supports resource adapters that provide the following transaction levels:

XATransaction

This means the resource adapter can participate in a distributed transaction managed by WebLogic's transaction manager, external to the resource adapter. When a J2EE component uses a connection to the EIS in a distributed transaction, WebLogic ensures that the associated XA resource is enlisted with the transaction manager. Later, when the J2EE component closes the connection, WebLogic de-lists the XA resource from the transaction manager and cleans up the actual connection to the EIS when the transaction has completed successfully.

LocalTransaction

This setting enables the resource adapter to participate in local transactions only. Unlike the XATransaction setting, such a connection to the EIS cannot participate in the 2PC protocol. The local transaction is bound by the lifetime of the EIS connection. Thus, WebLogic initiates a local transaction when a client requests a connection to the EIS, and commits the local transaction when the client releases the connection. It also cleans up the actual connection to the EIS when the transaction completes successfully.

NoTransaction

This setting indicates that the resource adapter supports neither local nor distributed transactions. Any connection to the EIS obtained using the resource adapter should not be used within an existing transaction context.

Remember, a local transaction is limited in scope and managed by the single EIS resource manager itself. A distributed (XA) transaction can span multiple resource managers, and is coordinated by WebLogic's transaction manager using the 2PC protocol.

In fact, WebLogic does allow a single resource adapter configured for local transactions to participate in an XA transaction. In this case, when the resources in the XA transaction are called upon to prepare, the prepare is first invoked on the XA resources. Only if all XA resources vote to commit is the local transaction committed. If this local transaction successfully commits, all the other XA resources are instructed to commit. If the local transaction fails to commit, the XA transaction and all the other XA resources involved are asked to roll back. As you can see, this neat trick works only if no more than one local transaction resource adapter is involved in an XA transaction. If you attempt to enlist multiple resource adapters that are configured for local transactions, the XA transaction will fail with an exception. See Chapter 5 for another example of this two-phase commit emulation.