17.2. Datasource Parameters

Common Datasource Parameters

<mbean>

A standard JBoss MBean deployment.

<depends>

The ObjectName of an MBean service this ConnectionFactory or DataSource deployment depends upon. The connection manager service will not be started until the dependent services have been started.

<jndi-name>

The JNDI name under which the Datasource should be bound.

<use-java-context>

Boolean value indicating whether the jndi-name should be prefixed with java:. This prefix causes the Datasource to only be accessible from within the JBoss Enterprise Application Platform virtual machine. Defaults to TRUE.

<user-name>

The user name used to create the connection to the datasource.

Note

Not used when security is configured.

<password>

The password used to create the connection to the datasource.

Note

Not used when security is configured.

<transaction-isolation>

The default transaction isolation of the connection. If not specified, the database-provided default is used.

Possible values for <transaction-isolation>

• TRANSACTION_READ_UNCOMMITTED
• TRANSACTION_READ_COMMITTED
• TRANSACTION_REPEATABLE_READ
• TRANSACTION_SERIALIZABLE
• TRANSACTION_NONE

<new-connection-sql>

An SQL statement that is executed against each new connection. This can be used to set up the connection schema, for instance.

<check-valid-connection-sql>

An SQL statement that is executed before the connection is checked out from the pool to make sure it is still valid. If the SQL statement fails, the connection is closed and a new one is created.

<valid-connection-checker-class-name>

A class that checks whether a connection is valid using a vendor-specific mechanism.

<exception-sorter-class-name>

A class that parses vendor-specific messages to determine whether SQL errors are fatal, and destroys the connection if so. If empty, no errors are treated as fatal.

<track-statements>

Whether to monitor for un-closed Statements and ResultSets and issue warnings when they have not been closed. The default value is NOWARN.

<prepared-statement-cache-size>

The number of prepared statements per connection to be kept open and reused in subsequent requests. They are stored in a Least Recently Used (LRU) cache. The default value is 0, meaning that no cache is kept.

<share-prepared-statements>

When the <prepared-statement-cache-size> is non-zero, determines whether two requests in the same transaction should return the same statement. Defaults to FALSE.

Example 17.1. Using <share-prepared-statements>

The goal is to work around questionable driver behavior, where the driver applies auto-commit semantics to local transactions.

       Connection c = dataSource.getConnection(); // auto-commit == false
       PreparedStatement ps1 = c.prepareStatement(...);
       ResultSet rs1 = ps1.executeQuery();
       PreparedStatement ps2 = c.prepareStatement(...);
       ResultSet rs2 = ps2.executeQuery();

This assumes that the prepared statements are the same. For some drivers, ps2.executeQuery() automatically closes rs1, so you actually need two real prepared statements behind the scenes. This only applies to the auto-commit semantic, where re-running the query starts a new transaction automatically. For drivers that follow the specification, you can set it to TRUE to share the same real prepared statement.

<set-tx-query-timeout>

Whether to enable query timeout based on the length of time remaining until the transaction times out. Defaults to FALSE.

<query-timeout>

The maximum time, in seconds, before a query times out. You can override this value by setting <set-tx-query-timeout> to TRUE.

<type-mapping>

A pointer to the type mapping in conf/standardjbosscmp.xml. This element is a child element of <metadata>. A legacy from JBoss4.

<validate-on-match>

Whether to validate the connection when the JCA layer matches a managed connection, such as when the connection is checked out of the pool. With the addition of <background-validation> this is not required. It is usually not necessary to specify TRUE for <validate-on-match> in conjunction with specifying TRUE for <background-validation>. Defaults to TRUE.

<prefill>

Whether to attempt to prefill the connection pool to the minimum number of connections. Only supporting pools (OnePool) support this feature. A warning is logged if the pool does not support prefilling. Defaults to TRUE.

<background-validation>

Background connection validation reduces the overall load on the RDBMS system when validating a connection. When using this feature, EAP checks whether the current connection in the pool a separate thread (ConnectionValidator). <background-validation-minutes> depends on this value also being set to TRUE. Defaults to FALSE.

Warning

The <background-validation> parameter has been deprecated and is no longer supported: set the <background-validation-millis> parameter to a value greater than 0 and background validation will be enabled automatically.

<background-validation-millis>

Background connection validation reduces the overall load on the RDBMS system when validating a connection. Setting this parameter means that JBoss will attempt to validate the current connections in the pool as a separate thread (ConnectionValidator). This parameter's value defines the interval for which the ConnectionValidator runs. The value should differ from the <idle-timeout-minutes > value). The default value of the property is 0. If <background-validation-millis> is set to a value greater than 0, the background validation is enabled.

This value should not be the same as your <idle-timeout-minutes> value.

Note

You should set this to a smaller value than <idle-timeout-minutes>, unless you have specified <min-pool-size> a minimum pool size set.

<idle-timeout-minutes>

The maximum time, in minutes, before an idle connection is closed. A value of 0 disables timeout. Defaults to 15 minutes.

<track-connection-by-tx>

Whether the connection should be locked to the transaction, instead of returning it to the pool at the end of the transaction. In previous releases, this was true for local connection factories and false for XA connection factories. The default is now true for both local and XA connection factories, and the element has been deprecated.

<interleaving>

Enables interleaving for XA connection factories.

<background-validation-minutes>

How often, in minutes, the ConnectionValidator runs. Default to 0 mills.

Warning

The <background-validation-minutes> parameter has been deprecated and is no longer supported: use the <background-validation-millis> parameter instead.

Note

You should set this to a smaller value than <idle-timeout-minutes>, unless you have specified <min-pool-size> a minimum pool size set.

<url-delimiter>, <url-property>, <url-selector-strategy-class-name>

Parameters dealing with database failover. As of JBoss Enterprise Application Platform 5.1, these are configured as part of the main datasource configuration. In previous versions, <url-delimiter> appeared as <url-delimiter>.

<stale-connection-checker-class-name>

An implementation of org.jboss.resource.adapter.jdbc.StateConnectionChecker that decides whether SQLExceptions that notify of bad connections throw the org.jboss.resource.adapter.jdbc.StateConnectionException exception.

<max-pool-size>

The maximum number of connections allowed in the pool. If undefined, the size defaults to 10. The value in the example datasource definition (<JBOSS_HOME>/server/<PROFILE>/deploy/hsqldb-ds.xml) is set to 20.

<min-pool-size>

The minimum number of connections maintained in the pool. Unless <prefill> is TRUE, the pool remains empty until the first use, at which point the pool is filled to the <min-pool-size>. When the pool size drops below the <min-pool-size> due to idle timeouts, the pool is refilled to the <min-pool-size>. Defaults to 0.

<blocking-timeout-millis>

The length of time, in milliseconds, to wait for a connection to become available when all the connections are checked out. Defaults to 30000, which is 30 seconds.

<use-fast-fail>

Whether to continue trying to acquire a connection from the pool even if the previous attempt has failed, or begin failover. This is to address performance issues where validation SQL takes significant time and resources to execute. Defaults to FALSE.

Parameters for javax.sql.XADataSource Usage

<connection-url>

The JDBC driver connection URL string

<driver-class>

The JDBC driver class implementing the java.sql.Driver

<connection-property>

Used to configure the connections retrieved from the java.sql.Driver.

Example 17.2. Example <connection-property>

       <connection-property name="char.encoding">UTF-8</connection-property>

Parameters for javax.sql.XADataSource Usage

<xa-datasource-class>

The class implementing the XADataSource

<xa-datasource-property>

Properties used to configure the XADataSource.

Example 17.3. Example <xa-datasource-property> Declarations

<xa-datasource-property name="IfxWAITTIME">10</xa-datasource-property>
<xa-datasource-property name="IfxIFXHOST">myhost.mydomain.com</xa-datasource-property>
<xa-datasource-property name="PortNumber">1557</xa-datasource-property>
<xa-datasource-property name="DatabaseName">mydb</xa-datasource-property>
<xa-datasource-property name="ServerName">myserver</xa-datasource-property>

<xa-resource-timeout>

The number of seconds passed to XAResource.setTransactionTimeout() when not zero.

<isSameRM-override-value>

When set to FALSE, fixes some problems with Oracle databases.

<no-tx-separate-pools>

Pool transactional and non-transactional connections separately

Warning

Using this option will cause your total pool size to be twice max-pool-size, because two actual pools will be created.

Used to fix problems with Oracle.

Security Parameters

<application-managed-security>

Uses the username and password passed on the getConnection or createConnection request by the application.

<security-domain>

Uses the identified login module configured in conf/login-module.xml.

<security-domain-and-application>

Uses the identified login module configured in conf/login-module.xml and other connection request information supplied by the application, for example JMS Queues and Topics.

Parameters for XA Recovery in the JCA Layer

<recover-user-name>

The user with credentials to perform a recovery operation.

<recover-password>

Password of the user with credentials to perform a recovery operation.

<recover-security-domain>

Security domain for recovery.

<no-recover>

Excludes a datasource from recovery.