Module io.helidon.integrations.jta.jdbc
Package io.helidon.integrations.jta.jdbc

Class JtaDataSource

  • All Implemented Interfaces:
    Wrapper, CommonDataSource, DataSource, javax.transaction.Synchronization
    public final class JtaDataSource
extends AbstractDataSource
implements javax.transaction.Synchronization
    An AbstractDataSource and a Synchronization that wraps another DataSource that is known to not behave correctly in the presence of JTA transaction management, such as one supplied by any of several freely and commercially available connection pools, and that makes such a non-JTA-aware DataSource behave as sensibly as possible in the presence of a JTA-managed transaction.

    Thread Safety

    Instances of this class are safe for concurrent use by multiple threads. No such guarantee obviously can be made about the DataSource wrapped by any given instance of this class.

    Note that the JDBC specification places no requirement on any implementor to make any implementations of any JDBC constructs thread-safe.

    • Method Detail

      • registerWith

        public boolean registerWith​(Consumer<? super javax.transaction.Synchronization> registrar)
        If there is an active transaction, registers this JtaDataSource with the supplied registrar, which is most commonly—but is not required to be—a reference to the TransactionSynchronizationRegistry.registerInterposedSynchronization(Synchronization) method.

        If there is no currently active transaction, no action is taken.

        Parameters:
        registrar - a Consumer that may accept this JtaDataSource if there is a currently active transaction; must not be null
        Returns:
        true if registration occurred; false otherwise
        Throws:
        NullPointerException - if registrar is null
        RuntimeException - if the supplied registrar's accept method throws a RuntimeException

      • beforeCompletion

        public void beforeCompletion()
        Implements the Synchronization.beforeCompletion() method to do nothing.
        Specified by:
        beforeCompletion in interface javax.transaction.Synchronization

      • afterCompletion

        public void afterCompletion​(int status)
        Ensures that any thread-associated connections are properly committed, restored to their initial states, closed where appropriate and removed from the system when a definitionally thread-scoped JTA transaction commits or rolls back.
        Specified by:
        afterCompletion in interface javax.transaction.Synchronization
        Parameters:
        status - the status of the transaction after completion; must be either Status.STATUS_COMMITTED or Status.STATUS_ROLLEDBACK
        Throws:
        IllegalArgumentException - if status is neither Status.STATUS_COMMITTED nor Status.STATUS_ROLLEDBACK

      • getConnection

        public Connection getConnection​(String username,
                                String password)
                         throws SQLException
        Returns a special kind of Connection that is sourced from an underlying DataSource.

        The Connection returned by this method:

        • is never null (unless the underlying DataSource is not JDBC-compliant)
        • is exactly the Connection returned by the underlying DataSource when there is no JTA transaction in effect at the time that this method is invoked

        Otherwise, when a JTA transaction is in effect, the Connection returned by this method:

        • is the same Connection returned by prior invocations of this method with the same credentials (or no credentials) on the same thread during the lifespan of a JTA transaction. That is, the Connection is "pinned" to the current thread for the lifespan of the transaction
        • is not actually closeable when a JTA transaction is in effect. The Connection.close() method will behave from the standpoint of the caller as if it functions normally, but its invocation will not actually be propagated to the underlying DataSource's connection. The fact that it was in fact invoked will be stored, and at such time that the JTA transaction completes this Connection will be closed at that point.
        • has its autocommit status set to false
        • will have Connection.commit() called on it when the JTA transaction commits
        • will have Connection.rollback() called on it when the JTA transaction rolls back
        • will have its autocommit status restored to its original value after the transaction completes
        Specified by:
        getConnection in interface DataSource
        Parameters:
        username - the username to use to acquire an underlying Connection; may be null
        password - the password to use to acquire an underlying Connection; may be null
        Returns:
        a non-null Connection
        Throws:
        SQLException - if an error occurs
        RuntimeException - if the BooleanSupplier supplied at construction time that reports a transaction's status throws a RuntimeException, or if the Supplier supplied at construction time that retrieves a delegate DataSource throws a RuntimeException
        See Also:
        DataSource.getConnection(), DataSource.getConnection(String, String)