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 element.
The XA resource can be associated with a Transaction in two ways:
- Setting 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 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 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
|
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". |
|
Required
Once |
The fully qualified class name for the XADataSource implementation in the JDBC Driver. |
|
Optional
Multiple |
Additional property values that will be supplied to the XADataSource. For example:
myDatabase
|
|
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:
MyXADS
true
false
oracle.jdbc.xa.client.OracleXADataSource
jdbc:oracle:oci8:@name
scott
tiger
org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
Connection Management
Once a connection has been obtained, the following elements can be used to determine how it is managed by the connector:
|
Default 0
Once |
The minimum number of connections that will be retained in the connection pool. |
|
Default 20
Once |
The maximum number of connections that will be entered in the connection pool. |
|
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 connections have been allocated, the thread nevers blocks but instead allocates a new connection. |
|
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.
|
|
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.
|
|
Optional
Once |
An SQL statement that will be executed immediately after a connection is created. |
|
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.
|
|
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.
|
|
