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,
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.
The following elements are used to configure the DataSource
|The name with which this DataSource will be bound into JNDI.
A value of "MyDS" will be bound to the absolute name "java:/MyDS".
|The fully qualified class name for the XADataSource implementation in
the JDBC Driver.
Additional property values that will be supplied to the XADataSource.
|If specified, overrides the value returned from isSameRM() for
this XAResource. This can be used to work around drivers that do not implments
An example of a very simple configuration for connecting to an Oracle database
using XA would be:
Once a connection has been obtained, the following elements can be used to
determine how it is managed by the connector:
|The minimum number of connections that will be retained in the connection
|The maximum number of connections that will be entered in the connection
|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.
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.
The isolation level to use for this connection.
This can be specified
using the constants defined in java.sql.Connection:
Alternatively an integer value can be used to specify driver-specific
If omitted, this will default to the default isolation level provided
by the database and driver.
|An SQL statement that will be executed immediately after a connection
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
See Handling Connection Errors for more
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