5.3. Configuring JDBC DataSources

Rather than configuring the connection manager factory related MBeans discussed in the previous section via a mbean services deployment descriptor, JBoss provides a simplified datasource centric descriptor. This is transformed into the standard jboss-service.xml MBean services deployment descriptor using a XSL transform applied by the org.jboss.deployment.XSLSubDeployer included in the jboss-jca.sar deployment. The simplified configuration descriptor is deployed the same as other deployable components. The descriptor must be named using a *-ds.xml pattern in order to be recognized by the XSLSubDeployer.

Multiple datasource configurations may be specified in a configuration deployment file. The child elements of the datasources root are:

mbean: Any number mbean elements may be specified to define MBean services that should be included in the jboss-service.xml descriptor that results from the transformation. This may be used to configure services used by the datasources.

no-tx-datasource: This element is used to specify the (org.jboss.resource.connectionmanager) NoTxConnectionManager service configuration. NoTxConnectionManager is a JCA connection manager with no transaction support. The no-tx-datasource child element schema is given in Figure 5.6, “The non-transactional DataSource configuration schema”.

local-tx-datasource: This element is used to specify the (org.jboss.resource.connectionmanager) LocalTxConnectionManager service configuration. LocalTxConnectionManager implements a ConnectionEventListener that implements XAResource to manage transactions through the transaction manager. To ensure that all work in a local transaction occurs over the same ManagedConnection, it includes a xid to ManagedConnection map. When a Connection is requested or a transaction started with a connection handle in use, it checks to see if a ManagedConnection already exists enrolled in the global transaction and uses it if found. Otherwise, a free ManagedConnection has its LocalTransaction started and is used. The local-tx-datasource child element schema is given in Figure 5.7, “The non-XA DataSource configuration schema”

xa-datasource: This element is used to specify the (org.jboss.resource.connectionmanager) XATxConnectionManager service configuration. XATxConnectionManager implements a ConnectionEventListener that obtains the XAResource to manage transactions through the transaction manager from the adaptor ManagedConnection. To ensure that all work in a local transaction occurs over the same ManagedConnection, it includes a xid to ManagedConnection map. When a Connection is requested or a transaction started with a connection handle in use, it checks to see if a ManagedConnection already exists enrolled in the global transaction and uses it if found. Otherwise, a free ManagedConnection has its LocalTransaction started and is used. The xa-datasource child element schema is given in Figure 5.8, “The XA DataSource configuration schema”.

ha-local-tx-datasource: This element is identical to local-tx-datasource, with the addition of the experimental datasource failover capability allowing JBoss to failover to an alternate database in the event of a database failure.

ha-xa-datasource: This element is identical to xa-datasource, with the addition of the experimental datasource failover capability allowing JBoss to failover to an alternate database in the event of a database failure.

Figure 5.6. The non-transactional DataSource configuration schema

Figure 5.7. The non-XA DataSource configuration schema

Figure 5.8. The XA DataSource configuration schema

Figure 5.9. The schema for the experimental non-XA DataSource with failover

Figure 5.10. The schema for the experimental XA Datasource with failover

Elements that are common to all datasources include:

jndi-name: The JNDI name under which the DataSource wrapper will be bound. Note that this name is relative to the java:/ context, unless use-java-context is set to false. DataSource wrappers are not usable outside of the server VM, so they are normally bound under the java:/, which isn't shared outside the local VM.

use-java-context: If this is set to false the the datasource will be bound in the global JNDI context rather than the java: context.

user-name: This element specifies the default username used when creating a new connection. The actual username may be overridden by the application code getConnection parameters or the connection creation context JAAS Subject.

password: This element specifies the default password used when creating a new connection. The actual password may be overridden by the application code getConnection parameters or the connection creation context JAAS Subject.

application-managed-security: Specifying this element indicates that connections in the pool should be distinguished by application code supplied parameters, such as from getConnection(user, pw).

security-domain: Specifying this element indicates that connections in the pool should be distinguished by JAAS Subject based information. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute.

security-domain-and-application: Specifying this element indicates that connections in the pool should be distinguished both by application code supplied parameters and JAAS Subject based information. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute.

min-pool-size: This element specifies the minimum number of connections a pool should hold. These pool instances are not created until an initial request for a connection is made. This default to 0.

max-pool-size: This element specifies the maximum number of connections for a pool. No more than the max-pool-size number of connections will be created in a pool. This defaults to 20.

blocking-timeout-millis: This element specifies the maximum time in milliseconds to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and will never throw an exception if creating a new connection takes an inordinately long time. The default is 5000.

idle-timeout-minutes: This element specifies the maximum time in minutes a connection may be idle before being closed. The actual maximum time depends also on the IdleRemover scan time, which is 1/2 the smallest idle-timeout-minutes of any pool.

new-connection-sql: This is a SQL statement that should be executed when a new connection is created. This can be used to configure a connection with database specific settings not configurable via connection properties.

check-valid-connection-sql: This is a SQL statement that should be run on a connection before it is returned from the pool to test its validity to test for stale pool connections. An example statement could be: select count(*) from x.

exception-sorter-class-name: This specifies a class that implements the org.jboss.resource.adapter.jdbc.ExceptionSorter interface to examine database exceptions to determine whether or not the exception indicates a connection error. Current implementations include:

org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter

org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter

org.jboss.resource.adapter.jdbc.vendor.SybaseExceptionSorter

org.jboss.resource.adapter.jdbc.vendor.InformixExceptionSorte

valid-connection-checker-class-name: This specifies a class that implements the org.jboss.resource.adapter.jdbc.ValidConnectionChecker interface to provide a SQLException isValidConnection(Connection e) method that is called with a connection that is to be returned from the pool to test its validity. This overrides the check-valid-connection-sql when present. The only provided implementation is org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker.

track-statements: This boolean element specifies whether to check for unclosed statements when a connection is returned to the pool. If true, a warning message is issued for each unclosed statement. If the log4j category org.jboss.resource.adapter.jdbc.WrappedConnection has trace level enabled, a stack trace of the connection close call is logged as well. This is a debug feature that can be turned off in production.

prepared-statement-cache-size: This element specifies the number of prepared statements per connection in an LRU cache, which is keyed by the SQL query. Setting this to zero disables the cache.

depends: The depends element specifies the JMX ObjectName string of a service that the connection manager services depend on. The connection manager service will not be started until the dependent services have been started.

type-mapping: This element declares a default type mapping for this datasource. The type mapping should match a type-mapping/name element from standardjbosscmp-jdbc.xml.

Additional common child elements for both no-tx-datasource and local-tx-datasource include:

connection-url: This is the JDBC driver connection URL string, for example, jdbc:hsqldb:hsql://localhost:1701.

driver-class: This is the fully qualified name of the JDBC driver class, for example, org.hsqldb.jdbcDriver.

connection-property: The connection-property element allows you to pass in arbitrary connection properties to the java.sql.Driver.connect(url, props) method. Each connection-property specifies a string name/value pair with the property name coming from the name attribute and the value coming from the element content.

Elements in common to the local-tx-datasource and xa-datasource are:

transaction-isolation: This element specifies the java.sql.Connection transaction isolation level to use. The constants defined in the Connection interface are the possible element content values and include:

TRANSACTION_READ_UNCOMMITTED

TRANSACTION_READ_COMMITTED

TRANSACTION_REPEATABLE_READ

TRANSACTION_SERIALIZABLE

TRANSACTION_NONE

no-tx-separate-pools: The presence of this element indicates that two connection pools are required to isolate connections used with JTA transaction from those used without a JTA transaction. The pools are lazily constructed on first use. Its use case is for Oracle (and possibly other vendors) XA implementations that don't like using an XA connection with and without a JTA transaction.

The unique xa-datasource child elements are:

track-connection-by-tx: Specifying a true value for this element makes the connection manager keep an xid to connection map and only put the connection back in the pool when the transaction completes and all the connection handles are closed or disassociated (by the method calls returning). As a side effect, we never suspend and resume the xid on the connection's XAResource. This is the same connection tracking behavior used for local transactions.

The XA spec implies that any connection may be enrolled in any transaction using any xid for that transaction at any time from any thread (suspending other transactions if necessary). The original JCA implementation assumed this and aggressively delisted connections and put them back in the pool as soon as control left the EJB they were used in or handles were closed. Since some other transaction could be using the connection the next time work needed to be done on the original transaction, there is no way to get the original connection back. It turns out that most XADataSource driver vendors do not support this, and require that all work done under a particular xid go through the same connection.

xa-datasource-class: The fully qualified name of the javax.sql.XADataSource implementation class, for example, com.informix.jdbcx.IfxXADataSource.

xa-datasource-property: The xa-datasource-property element allows for specification of the properties to assign to the XADataSource implementation class. Each property is identified by the name attribute and the property value is given by the xa-datasource-property element content. The property is mapped onto the XADataSource implementation by looking for a JavaBeans style getter method for the property name. If found, the value of the property is set using the JavaBeans setter with the element text translated to the true property type using the java.beans.PropertyEditor for the type.

isSameRM-override-value: A boolean flag that allows one to override the behavior of the javax.transaction.xa.XAResource.isSameRM(XAResource xaRes) method behavior on the XA managed connection. If specified, this value is used unconditionally as the isSameRM(xaRes) return value regardless of the xaRes parameter.

The failover options common to ha-xa-datasource and ha-local-tx-datasource are:

url-delimeter: This element specifies a character used to separate multiple JDBC URLs.

url-property: In the case of XA datasources, this property specifies the name of the xa-datasource-property that contains the list of JDBC URLs to use.

Example configurations for many third-party JDBC drivers are included in the JBOSS_DIST/docs/examples/jca directory. Current example configurations include: