Use of DataSource, XADataSource and Driver implementations for JDBC access in JBoss EAP

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 7
  • 6
• <JBOSS_HOME>/docs/schema/jboss-as-datasources_1_*.xsd

Issue

• How does JBoss establish JDBC connections?
• How does a JBoss <datasource> or <xa-datasource> pool relate to 3rd party implementation of the following interfaces:
  • Content from docs.oracle.com is not included.java.sql.Driver
  • Content from docs.oracle.com is not included.javax.sql.DataSource
  • Content from docs.oracle.com is not included.javax.sql.XADataSource

Resolution

Implementation

• For each configured datasource or xa-datasource (in the JBoss EAP standalone*.xml or domain.xml), JBoss creates a singleton datasource instance (in each JBoss server instance) which manages a pool of connections where each connection is created by delegation to an instance of a 3rd party supplied class which implements one of the following interfaces:
  • Content from docs.oracle.com is not included.java.sql.Driver
  • Content from docs.oracle.com is not included.javax.sql.DataSource
  • Content from docs.oracle.com is not included.javax.sql.XADataSource
• The 3rd party class which implements one of these three interfaces is used as follows to create connections to populate the pool:
  • If the class implements the Driver interface, the Content from docs.oracle.com is not included.java.sql.Driver.connect(String url, Properties info) method is used to create new (non-XA) connections. This class/method can only be used by a JBoss (non-XA) datasource.
  • If the class implements the DataSource interface, the Content from docs.oracle.com is not included.javax.sql.DataSource.getConnection(String username, String password) method is used to create new non-XA connections. This class/method can only be used by a JBoss (non-XA) datasource.
  • If the class implements the XADataSource interface, the Content from docs.oracle.com is not included.javax.sql.XADataSource.getXAConnection(String username, String password) method is used to create new XA connections. This class/method can only be used by a JBoss xa-datasource.
• Connections created by the 3rd party implementation class are retained by the JBoss pool to satisfy application-initiated connection requests.

Configuration

Note that it is recommended that creation of a database driver module, driver registration and datasource creation be done using JBoss CLI. The examples below illustrate the resulting XML configuration.

1. The class used to create connections should be specified by the <driver-class>, <datasource-class> or <xa-datasource-class> property in the <driver> configuration (in the <drivers> section of the JBoss EAP standalone*.xml or domain.xml).

           </datasources>
               ...
               <drivers>
                   ...
                   <driver name="myDbDriver" module="some.package.db">
                       <!-- The driver-class is usually optional as it may be detected automatically -->
                       <driver-class>some.package.db.Driver</driver-class>
                       <!-- datasource-class is usually avoided if a java.sql.Driver implementation is available -->
                       <datasource-class>some.package.db.DataSource</xa-datasource>
                       <!-- xa-datasource-class is required if using an xa-datasource -->
                       <xa-datasource-class>some.package.db.XaDataSource</xa-datasource-class>
                   </driver>
               </drivers>
           </datasources>
   

   These properties can also be included within each <datasource> or <xa-datasource> section but this is not recommended.

2. Each [xa-]datasource (in the JBoss EAP standalone*.xml or domain.xml) should include a single reference to the registered driver:

               <datasource jndi-name="java:jboss/datasources/myProdDB" pool-name="myProdDB" enabled="true">
                   ...
                   <driver>myDBDriver</driver>
                   ...
               </datasource>
   

Notes

• In most 3rd party JDBC implementations, an appropriate connection provider class for (non-XA) datasources is usually detected/loaded automatically based upon the META-INF/services/java.sql.Driver file contained within the JDBC driver JAR file. In such cases, neither <driver-class> nor <datasource-class> are required for (non-XA) datasource pools.
• Use of an implementation of the Driver interface (rather than DataSource) is often preferred for non-XA connections since the Driver API provides a standardized mechanism for passing connection configuration properties.
• Though used by JBoss for a similar purpose (i.e. to create connections), the driver and datasource APIs are not interchangeable. Likewise, the <driver-class>, <datasource-class> and <xa-datasource-class> properties are not interchangeable.
  • A driver class (only usable to create non-XA connections) must implement Content from docs.oracle.com is not included.java.sql.Driver.
  • A non-XA datasource class (only usable to create non-XA connections) must implement Content from docs.oracle.com is not included.javax.sql.DataSource.
  • An XA datasource class (only usable to create XA connections) must implement Content from docs.oracle.com is not included.javax.sql.XADataSource.
• The word "driver" is often used in different ways
  • Sometimes "driver" refers to a specific class implementing the java.sql.Driver interface
  • Sometimes "driver" refers to the 3rd party JAR file which contains the implementation of one or more of the above interfaces
  • Sometimes "driver" refers to the functionality provided by the entire set of classes and interfaces within a 3rd party JAR.

References

• Specifying driver-class or datasource-class for non-XA JDBC datasource pools in JBoss EAP
• JDBC driver cannot be cast to javax.sql.DataSource or javax.sql.XADataSource in JBoss EAP
• JDBC DataSource or XADataSource cannot be cast to java.sql.Driver in JBoss EAP
• "WFLYJCA0114: Failed to load datasource class: ..." referencing unused class in JBoss EAP
• Exception java.sql.SQLException: Invalid Oracle URL specified: OracleDataSource.makeURL when trying to use an non-XA Oracle datasource

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.