XA DataSource Configuration

If an application needs to access multiple resources in a single transaction, then the XA protocol should be used to ensure that the state remains consistent between them. The XA protocol supports the use of two-phase commit, ensuring that modifications between the multiple resources either commit together or are rolled back together.

It should be noted that for many resource managers, using XA adds substantial overhead to all operations not just the commit. As a result, XA should be used only when necessary.

Connection Transaction Types

An XA datasource is configured in a -ds.xml file using a <xa-datasource> element.

The XA resource can be associated with a Transaction in two ways:

  • Setting <track-connection-by-tx> to true associates the connection for the entire duration of the Transaction. Once the resource has been used, the Connection remains associated with the Transaction until it commits or rolls back; this is similar to a local-transaction connection, except that a two-phase protocol is used at commit time.
  • Setting <track-connection-by-tx> to false associates the connection only for the time it is actively used by the application. Once the application returns the Connection to the pool (by invoking its close() method), the Transaction remains active but the Connection is disassociated from it. The next time a Connection is needed to interact with the resource, any one can be selected from the pool and reassociated with the Transaction.

In most applications, setting <track-connection-by-tx> to true is recommended. Often, the overhead of disassocating and reassociating the Connection exceeds the cost of keeping the original association active for longer. Further, this functionality is often not implemented by the underlying driver or may be problematic.

Connection Properties

The following elements are used to configure the DataSource

<jndi-name> Required
Once
The name with which this DataSource will be bound into JNDI. A value of "MyDS" will be bound to the absolute name "java:/MyDS".
<xa-datasource-class> Required
Once
The fully qualified class name for the XADataSource implementation in the JDBC Driver.
<xa-datasource-property> Optional
Multiple

Additional property values that will be supplied to the XADataSource. For example:

<xa-datasource-property name="databaseName">
  myDatabase
</xa-datasource-property>
<isSameRM-override-value> Optional
Once
If specified, overrides the value returned from isSameRM() for this XAResource. This can be used to work around drivers that do not implments isSameRM() correctly.

An example of a very simple configuration for connecting to an Oracle database using XA would be:

<datasources>
<xa-datasource>
<jndi-name>MyXADS</jndi-name>
<track-connection-by-tx>true</track-connection-by-tx>
<isSameRM-override-value>false</isSameRM-override-value>
<xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
<xa-datasource-property name="URL">jdbc:oracle:oci8:@name</xa-datasource-property>
<xa-datasource-property name="User">scott</xa-datasource-property>
<xa-datasource-property name="Password">tiger</xa-datasource-property>
<exception-sorter-class-name>
org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
</exception-sorter-class-name>
</xa-datasource>
</datasources>

Connection Management

Once a connection has been obtained, the following elements can be used to determine how it is managed by the connector:

<min-pool-size> Default 0
Once
The minimum number of connections that will be retained in the connection pool.
<max-pool-size> Default 20
Once
The maximum number of connections that will be entered in the connection pool.
<blocking-timeout-millis> Default 5000
Once
The amount of time that a thread will wait for a connection to be released if the pool is full. If less than <max-pool-size> connections have been allocated, the thread nevers blocks but instead allocates a new connection.
<idle-timeout-minutes> Default 15
Once

The approximate time that a connection will remain idle before being closed. Idle connections are checked for at an interval of half the lowest value for all connection pools; thus a connection may actually remain in the pool for between 1 and 1.5 times this value.

This value can be used to prevent errors when the underlying driver automatically closes idle connections.

<transaction-isolation> Optional
Once

The isolation level to use for this connection.

This can be specified using the constants defined in java.sql.Connection:

  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_REPEATABLE_READ

Alternatively an integer value can be used to specify driver-specific levels.

If omitted, this will default to the default isolation level provided by the database and driver.

<new-connection-sql> Optional
Once
An SQL statement that will be executed immediately after a connection is created.
<valid-connection-sql> Optional
Once

An SQL statement that will be executed whenever a connection is obtained from the pool to determine if it is still usable. Any SQLException thrown will cause the connection to be discarded before it is returned to the application.

See Handling Connection Errors for more information.

<exception-sorter-class-name>

Optional
Once

The fully qualifed name of a class which can be used to detect SQLExceptions that indicate unusable connections. Should such an SQLException be thrown, then the connection will immediately be discarded from the pool.

See Handling Connection Errors for more information.