Class XADataSource

java.lang.Object
org.apache.tomcat.jdbc.pool.DataSourceProxy
org.apache.tomcat.jdbc.pool.DataSource
org.apache.tomcat.jdbc.pool.XADataSource
All Implemented Interfaces:
Wrapper, MBeanRegistration, CommonDataSource, ConnectionPoolDataSource, DataSource, XADataSource, ConnectionPoolMBean, PoolConfiguration
public class XADataSource extends DataSource implements XADataSource
XA-enabled data source for distributed transaction support.

Note that XA support is not provided by this class itself: XA capability comes from the data source configured through the dataSource or dataSourceJNDI attribute, which must implement XADataSource (see PoolConfiguration.setDataSource(Object)). A pool configured with only driverClassName and url pools plain JDBC connections; a request for an XA connection from such a pool fails with an explicit message naming the missing configuration rather than later, inside the transaction manager.

What the getXAConnection methods return is nevertheless not that configured data source's own handle: it is a session borrowed from the pool, whose close() returns the session to the pool instead of closing the physical connection. The deviations from the javax.sql contract that follow from this are stated on those methods.

  • Constructor Details

    • XADataSource

      public XADataSource()
      Constructor for reflection only. A default set of pool properties will be created.

    • XADataSource

      public XADataSource(PoolConfiguration poolProperties)
      Constructs a DataSource object wrapping a connection
      Parameters:
      poolProperties - The pool configuration

  • Method Details

    • getXAConnection

      public XAConnection getXAConnection() throws SQLException
      Get a database connection. XADataSource.getXAConnection()

      This implementation first checks that the pool can provide XA connections at all, and fails with an explicit configuration hint when it cannot.

      Deviation from the javax.sql contract: the returned XAConnection is a handle borrowed from the pool, not a freshly opened physical connection, so under load this call blocks waiting for a free session or fails with pool exhaustion rather than with a database error. Its close() returns the session to the pool instead of closing the physical connection; every XA branch started through the returned XAResource must therefore be completed - committed or rolled back - before close(), and neither the handle nor its XAResource may be used after it. A handle closed while a branch stands unresolved is not returned to the pool: the pool's return-time rollback unwinds only local work and can never resolve a branch that stands prepared, so the pool closes the session instead of handing another borrower a connection that carries that branch and the database locks held for it. The transaction manager's late commit or rollback of the abandoned branch then fails against the closed session rather than landing, silently, on a session that does not carry it.

      The connection obtained from the returned handle's PooledConnection.getConnection() is the driver's raw logical session, not a pool-managed connection: the pool's interceptors and features do not apply to it, and closing it invalidates the session under the pool's own notion of a live connection. Release the borrowed session by closing the handle, not that connection.

      Specified by:
      getXAConnection in interface XADataSource
      Overrides:
      getXAConnection in class DataSourceProxy
      Returns:
      the connection
      Throws:
      SQLException - Connection error

    • getXAConnection

      public XAConnection getXAConnection(String username, String password) throws SQLException
      Get a database connection. XADataSource.getXAConnection(String, String)

      This implementation first checks that the pool can provide XA connections at all, and fails with an explicit configuration hint when it cannot. The returned handle deviates from the javax.sql contract as described on getXAConnection(), and carries one deviation of its own: the given credentials are honored only when alternateUsernameAllowed is enabled, which it is not by default; otherwise the borrow proceeds under the pool's configured user name, exactly as DataSourceProxy.getConnection(String, String) does, and every XA branch started through this handle's XAResource runs under that identity, not the one passed in here.

      Specified by:
      getXAConnection in interface XADataSource
      Overrides:
      getXAConnection in class DataSourceProxy
      Parameters:
      username - The user name
      password - The password
      Returns:
      the connection
      Throws:
      SQLException - Connection error