6.6. Datasource Configuration
6.6.1. Datasource Parameters
Table 6.3. Datasource parameters common to non-XA and XA datasources
Parameter | Description |
---|---|
jndi-name | The unique JNDI name for the datasource. |
pool-name | The name of the management pool for the datasource. |
enabled | Whether or not the datasource is enabled. |
use-java-context |
Whether to bind the datasource to global JNDI.
|
spy |
Enable
spy functionality on the JDBC layer. This logs all JDBC traffic to the datasource. The logging-category parameter must also be set to org.jboss.jdbc .
|
use-ccm | Enable the cached connection manager. |
new-connection-sql | A SQL statement which executes when the connection is added to the connection pool. |
transaction-isolation |
One of the following:
|
url-delimiter | The delimiter for URLs in a connection-url for High Availability (HA) clustered databases. |
url-selector-strategy-class-name | A class that implements interface org.jboss.jca.adapters.jdbc.URLSelectorStrategy . |
security |
Contains child elements which are security settings. Refer to Table 6.8, “Security parameters”.
|
validation |
Contains child elements which are validation settings. Refer to Table 6.9, “Validation parameters”.
|
timeout |
Contains child elements which are timeout settings. Refer to Table 6.10, “Timeout parameters”.
|
statement |
Contains child elements which are statement settings. Refer to Table 6.11, “Statement parameters”.
|
Table 6.4. Non-XA datasource parameters
Parameter | Description |
---|---|
jta | Enable JTA integration for non-XA datasources. Does not apply to XA datasources. |
connection-url | The JDBC driver connection URL. |
driver-class | The fully-qualified name of the JDBC driver class. |
connection-property |
Arbitrary connection properties passed to the method
Driver.connect(url,props) . Each connection-property specifies a string name/value pair. The property name comes from the name, and the value comes from the element content.
|
pool |
Contains child elements which are pooling settings. Refer to Table 6.6, “Pool parameters common to non-XA and XA datasources”.
|
Table 6.5. XA datasource parameters
Parameter | Description |
---|---|
xa-datasource-property |
A property to assign to implementation class
XADataSource . Specified by name=value. If a setter method exists, in the format setName , the property is set by calling a setter method in the format of setName(value) .
|
xa-datasource-class |
The fully-qualified name of the implementation class
javax.sql.XADataSource .
|
driver |
A unique reference to the classloader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
|
xa-pool |
Contains child elements which are pooling settings. Refer to Table 6.6, “Pool parameters common to non-XA and XA datasources” and Table 6.7, “XA pool parameters”.
|
recovery |
Contains child elements which are recovery settings. Refer to Table 6.12, “Recovery parameters”.
|
Table 6.6. Pool parameters common to non-XA and XA datasources
Parameter | Description |
---|---|
min-pool-size | The minimum number of connections a pool holds. |
max-pool-size | The maximum number of connections a pool can hold. |
prefill | Whether to try to prefill the connection pool. An empty element denotes a true value. The default is false . |
use-strict-min | Whether the pool-size is strict. Defaults to false . |
flush-strategy |
Whether the pool should be flushed in the case of an error. Valid values are:
The default is
FailingConnectionOnly .
|
allow-multiple-users | Specifies if multiple users will access the datasource through the getConnection(user, password) method, and whether the internal pool type should account for this behavior. |
Table 6.7. XA pool parameters
Parameter | Description |
---|---|
is-same-rm-override | Whether the javax.transaction.xa.XAResource.isSameRM(XAResource) class returns true or false . |
interleaving | Whether to enable interleaving for XA connection factories. |
no-tx-separate-pools | Whether to create separate sub-pools for each context. This is required for Oracle datasources, which do not allow XA connections to be used both inside and outside of a JTA transaction. |
pad-xid | Whether to pad the Xid. |
wrap-xa-resource |
Whether to wrap the XAResource in an
org.jboss.tm.XAResourceWrapper instance.
|
Table 6.8. Security parameters
Parameter | Description |
---|---|
user-name | The username to use to create a new connection. |
password | The password to use to create a new connection. |
security-domain | Contains the name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration. |
reauth-plugin | Defines a reauthentication plugin to use to reauthenticate physical connections. |
Table 6.9. Validation parameters
Parameter | Description |
---|---|
valid-connection-checker |
An implementation of interface
org.jboss.jca.adaptors.jdbc.ValidConnectionChecker which provides a SQLException.isValidConnection(Connection e) method to validate a connection. An exception means the connection is destroyed. This overrides the parameter check-valid-connection-sql if it is present.
|
check-valid-connection-sql | An SQL statement to check validity of a pool connection. This may be called when a managed connection is taken from a pool for use. |
validate-on-match |
Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set. Mutually exclusive to
background validation .
|
background-validation |
Specifies that connections are validated on a background thread, rather than being validated prior to use. Mutually exclusive to
validate-on-match .
|
background-validation-millis | The amount of time, in milliseconds, that background validation runs. |
use-fast-fail |
If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to
false .
|
stale-connection-checker |
An instance of
org.jboss.jca.adapters.jdbc.StaleConnectionChecker which provides a Boolean isStaleConnection(SQLException e) method. If this method returns true , the exception is wrapped in an org.jboss.jca.adapters.jdbc.StaleConnectionException , which is a subclass of SQLException .
|
exception-sorter |
An instance of
org.jboss.jca.adapters.jdbc.ExceptionSorter which provides a Boolean isExceptionFatal(SQLException e) method. This method validates whether an exception should be broadcast to all instances of javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message.
|
Table 6.10. Timeout parameters
Parameter | Description |
---|---|
blocking-timeout-millis | The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, and exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds. |
idle-timeout-minutes |
The maximum time, in minutes, before an idle connection is closed. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest
idle-timeout-minutes of any pool.
|
set-tx-query-timeout |
Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to
false .
|
query-timeout | Timeout for queries, in seconds. The default is no timeout. |
allocation-retry | The number of times to retry allocating a connection before throwing an exception. The default is 0 , so an exception is thrown upon the first failure. |
allocation-retry-wait-millis |
How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
|
xa-resource-timeout |
If non-zero, this value is passed to method
XAResource.setTransactionTimeout .
|
Table 6.11. Statement parameters
Parameter | Description |
---|---|
track-statements |
Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked.
Valid values
|
prepared-statement-cache-size | The number of prepared statements per connection, in a Least Recently Used (LRU) cache. |
share-prepared-statements |
Whether asking for the same statement twice without closing it uses the same underlying prepared statement. The default is
false .
|
Table 6.12. Recovery parameters
Parameter | Description |
---|---|
recover-credential | A username/password pair or security domain to use for recovery. |
recover-plugin |
An implementation of class
org.jboss.jca.core.spi.recoveryRecoveryPlugin class, to be used for recovery.
|