Specifying driver-class or datasource-class for non-XA JDBC datasource pools in JBoss EAP

Solution Verified - Updated

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 7
    • 6
  • All database types

Issue

  • Should a driver-class or datasource-class be specified for non-XA JDBC pools?

Resolution

Configuring non-XA Pools

  • For JDBC 4 compliant drivers, neither a driver-class nor a datasource-class are required or recommended in most cases.
  • For drivers which are not JDBC4-compliant, it may be necessary to specify a driver-class or a datasource-class when configuring a non-XA pool.
    • Consult the 3rd party vendor documentation for the recommended class.
  • In certain cases, use of a datasource-class may be required if 3rd party functionality is available only when using an implementation of javax.sql.DataSource.
  • It is permissible to define either a datasource-class or a driver-class but never both.
    • Note that if using a static driver module the same rule applies across the datasource (pool) and driver (entry in the drivers subsection).
    • It is invalid to specify a driver-class or datasource-class in the datasource (pool) and also reference a driver entry which includes either a datasource-class or driver-class.

Configuring both XA and non-XA Pools using a Static Driver Module


If one or more XA pools are to be defined, they may share a single `driver` entry in the `drivers` subsection with one or more non-XA pools.
  • A driver entry in the drivers subsection is used to declare a driver that is provided as a static module in the JBoss EAP installation instead of a simple single-jar based deployment. The static module will contain one or more jar files which make up the 3rd party vendor's JDBC implementation.
  • It is not uncommon (since non-XA pools do not usually require any explicit connection provider class specification) to configure a driver which lists only an xa-datasource-class and which is shared by both XA and non-XA pools.
  • In such cases, non-XA pools will not use1 the xa-datasource-class - but will, instead, use the default java.sql.Driver implementation or the driver-class or datasource-class if specified.
1

The xa-datasource-class may be validated during load of the configuration even if no XA pool is defined.

Root Cause

  • There are two alternatives for connecting to a database when using a non-XA pool:
  • XA pools require specification of a class which implements Content from docs.oracle.com is not included.javax.sql.XADataSource
  • For non-XA pools, implementations of java.sql.Driver are usually preferred to implementations of javax.sql.DataSource because the Driver interface provides a standard mechanism for property configuration.
    • Note that, while both serve the same purpose (creating connections to a database), implementations of Driver and DataSource are not interchangeable.
    • An error may occur if a DataSource implementation class is specified as a driver-class or if a Driver implementation class is specified as a datasource-class.
  • The connection provider for XA pools must be provided using the xa-datasource-class and this property is also not interchangeable with either driver-class or datasource-class.
  • JDBC 4 compliant JDBC drivers (i.e. 3rd party vendor provided jar files which bundle an implementation of the JDBC 4 specification) specify the preferred driver in META-INF/services/java.sql.Driver.
  • JBoss EAP will automatically select an appropriate implementation of the java.sql.Driver class for non-XA pools if neither driver-class nor datasource-class are explicitly included in either the datasource or driver definition.
SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.