JBoss.org Community Documentation

13.13. Common DataSource parameters

  • <jndi-name> - the JNDI name under which the DataSource should be bound.

  • <use-java-context> - A boolean indicating if the jndi-name should be prefixed with java: which causes the DataSource to only be accessible from within the jboss server vm. The default is true.

  • <user-name> - the user name used when creating the connection (not used when security is configured)

  • <password> - the password used when creating the connection (not used when security is configured)

  • <transaction-isolation> - the default transaction isolation of the connection (unspecified means use the default provided by the database):

    • 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 the connection schema, etc.

  • <check-valid-connection-sql> - an sql statement that is executed before it is checked out from the pool to make sure it is still valid. If the sql fails, the connection is closed and new ones created.

  • <valid-connection-checker-class-name> - a class that can check whether a connection is valid using a vendor specific mechanism

  • <exception-sorter-class-name> - a class that looks at vendor specific messages to determine whether sql errors are fatal and thus the connection should be destroyed. If none specified, no errors will be treated as fatal.

  • <track-statements> - (a) whether to monitor for unclosed Statements and ResultSets and issue warnings when the user forgets to close them (default 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 LRU cache. The default is 0 (zero), meaning no cache.

  • <share-prepared-statements> - (b) with prepared statement cache enabled whether two requests in the same transaction should return the same statement (from jboss-4.0.2 - default false).

  • <set-tx-query-timeout> - whether to enable query timeout based on the length of time remaining until the transaction times out (default false - NOTE: This was NOT ported to 4.0.x until 4.0.3)

  • <query-timeout> - a static configuration of the maximum of seconds before a query times out (since 4.0.3)

  • <metadata/typemapping> - a pointer to the type mapping in conf/standardjbosscmp.xml (available from JBoss 4 and above)

  • <validate-on-match> - Prior to JBoss 4.0.5, connection validation occurred when the JCA layer attempted to match a managed connection. With the addition of <background-validation> this is no longer required. Specifying <validate-on-match> forces the old behavior. NOTE: this is typically NOT used in conjunction with <background-validation>

  • <prefill> - whether to attempt to prefill the connection pool to the minimum number of connections. NOTE: only supporting pools (OnePool) support this feature. A warning can be found in the logs if the pool does not support this. This feature will appear in JBoss 4.0.5.

  • <background-validation> - In JBoss 4.0.5, background connection validation as been added to reduce the overall load on the RDBMS system when validating a connection. When using this feature, JBoss will attempt to validate the current connections in the pool is a seperate thread (ConnectionValidator). Default is False.

  • <idle-timeout-minutes> - indicates the maximum time a connection may be idle before being closed. Default is 15 minutes.

  • <background-validation-minutes> - The interval, in minutes, that the ConnectionValidator will run. Default is 10 minutes. NOTE: It is prudent to set this value to something greater or less than the <idle-timeout-minutes>

  • <url-delimiter> - From JBoss5 database failover is part of the main datasource config

  • <url-property> - From JBoss5 database failover is part of the main datasource config

  • <url-selector-strategy-class-name> - From JBoss5 ONLY database failover is part of the main datasource config

  • <stale-connection-checker-class-name> - An implementation of org.jboss.resource.adapter.jdbc.StateConnectionChecker that will decide whether SQLExceptions that notify of bad connections throw org.jboss.resource.adapter.jdbc.StateConnectionException (from JBoss5)

From JBoss AS 3.2.6 and above, track-statements has a new option: 

<track-statements>nowarn</track-statements

This option closes Statements and ResultSets without a warning. It is also the new default value.

The purpose is to workaround 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();

Assuming the prepared statements are the same. For some drivers, ps2.executeQuery() will automatically close rs1 so we actually need two real prepared statements behind the scenes. This *should* only be for the auto-commit semantic where re-running the query starts a new transaction automatically. For drivers that follow the spec, you can set it to true to share the same real prepared statement.