Module io.helidon.integrations.jta.jdbc

Package io.helidon.integrations.jta.jdbc

Class JtaDataSource

java.lang.Object

io.helidon.integrations.jdbc.AbstractCommonDataSource

io.helidon.integrations.jdbc.AbstractDataSource

io.helidon.integrations.jta.jdbc.JtaDataSource

All Implemented Interfaces:

Synchronization, Wrapper, CommonDataSource, DataSource

@Deprecated(forRemoval=true,
            since="3.0.3")
public final class JtaDataSource
extends AbstractDataSource
implements Synchronization

Deprecated, for removal: This API element is subject to removal in a future version.

This class is slated for removal. It makes incorrect assumptions about threading in a JTA environment. Specifically, this class' implementation incorrectly assumes that the afterCompletion(int) method will be invoked on the same thread as the governing transaction, which is not necessarily the case, especially in the case of asynchronous rollbacks. As a result, Connections acquired by instances of this class may not be closed properly.

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. Nevertheless, a certain amount of unspecified thread safety must exist in all JDBC implementations or their constructs could never be enrolled in JTA-compliant transactions.

Constructor Summary

Constructors

Constructor	Description
JtaDataSource(Supplier<? extends DataSource> delegateSupplier, BooleanSupplier transactionIsActiveSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new JtaDataSource.
JtaDataSource(DataSource dataSource, BooleanSupplier transactionIsActiveSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new JtaDataSource.

Method Summary

Modifier and Type	Method	Description
void	afterCompletion(int status)	Deprecated, for removal: This API element is subject to removal in a future version. 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.
void	beforeCompletion()	Deprecated, for removal: This API element is subject to removal in a future version. Implements the Synchronization.beforeCompletion() method to do nothing.
Connection	getConnection()	Deprecated, for removal: This API element is subject to removal in a future version. Returns a special kind of Connection that is sourced from an underlying DataSource.
Connection	getConnection(String username, String password)	Deprecated, for removal: This API element is subject to removal in a future version. Returns a special kind of Connection that is sourced from an underlying DataSource.
boolean	registerWith(Consumer<? super Synchronization> registrar)	Deprecated, for removal: This API element is subject to removal in a future version. This method is slated for removal with no replacement.

Methods inherited from class io.helidon.integrations.jdbc.AbstractDataSource

isWrapperFor, unwrap

Methods inherited from class io.helidon.integrations.jdbc.AbstractCommonDataSource

getLoginTimeout, getLogWriter, getParentLogger, setLoginTimeout, setLogWriter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.sql.CommonDataSource

createShardingKeyBuilder, getParentLogger

Methods inherited from interface javax.sql.DataSource

createConnectionBuilder, getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter

Constructor Details

JtaDataSource

public JtaDataSource(DataSource dataSource,
 BooleanSupplier transactionIsActiveSupplier)

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new JtaDataSource.

Parameters:

dataSource - the DataSource instance to which operations will be delegated; must not be null

transactionIsActiveSupplier - a BooleanSupplier that returns true only if the current transaction, if any, is active; must not be null

Throws:

NullPointerException - if either parameter is null

See Also:

• JtaDataSource(Supplier, BooleanSupplier)

JtaDataSource

public JtaDataSource(Supplier<? extends DataSource> delegateSupplier,
 BooleanSupplier transactionIsActiveSupplier)

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new JtaDataSource.

Parameters:

delegateSupplier - a Supplier of DataSource instances to which operations will be delegated; must not be null

transactionIsActiveSupplier - an BooleanSupplier that returns true only if the current transaction, if any, is active; must not be null

Throws:

NullPointerException - if either parameter is null

Method Details

registerWith

@Deprecated(forRemoval=true)
public boolean registerWith(Consumer<? super Synchronization> registrar)

Deprecated, for removal: This API element is subject to removal in a future version.

This method is slated for removal with no replacement.

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()

Deprecated, for removal: This API element is subject to removal in a future version.

Implements the Synchronization.beforeCompletion() method to do nothing.

Specified by:

beforeCompletion in interface Synchronization

afterCompletion

public void afterCompletion(int status)

Deprecated, for removal: This API element is subject to removal in a future version.

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 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()
                         throws SQLException

Deprecated, for removal: This API element is subject to removal in a future version.

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 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

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)

getConnection

public Connection getConnection(String username,
 String password)
                         throws SQLException

Deprecated, for removal: This API element is subject to removal in a future version.

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)