Common Datasource Parameters

<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 unclosed Statements and ResultSets and issue warnings when they haven't been closed. The default value is NOWARN.

<prepared-statement-cach-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 3.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. Included for future compatible only, and currently has no effect. 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.

<metadata>><type-mapping>

A pointer to the type mapping in conf/standardjbosscmp.xml. 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 seperate thread (ConnectionValidator). <background-validation-minutes> depends on this value also being set to TRUE. Defaults to FALSE.

<idle-timeout-minutes>

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

<background-validation-minutes>

How often, in minutes, the ConnectionValidator runs. Defaults to 10 minutes.

Note

You should set this to a smallervalue 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-delimeter>.

<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. Defaults 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 3.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 3.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>

<isSameRM-override-value>

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

<no-tx-separate-pools>

Pool transactional and non-transactinal 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.