javax.sql

Interface XAConnection

All Superinterfaces:

PooledConnection

public interface XAConnection
extends PooledConnection

An object that provides support for distributed transactions. An XAConnection object may be enlisted in a distributed transaction by means of an XAResource object. A transaction manager, usually part of a middle tier server, manages an XAConnection object through the XAResource object.

An application programmer does not use this interface directly; rather, it is used by a transaction manager working in the middle tier server.

Since:

1.4

Method Summary

Modifier and Type	Method and Description
XAResource	getXAResource() Retrieves an XAResource object that the transaction manager will use to manage this XAConnection object's participation in a distributed transaction.
default void	setShardingKey(ShardingKey shardingKey) Specifies a shardingKey to use with this Connection
default void	setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey) Specifies a shardingKey and superShardingKey to use with this Connection
default boolean	setShardingKeyIfValid(ShardingKey shardingKey, int timeout) Sets and validates the sharding key for this connection.
default boolean	setShardingKeyIfValid(ShardingKey shardingKey, ShardingKey superShardingKey, int timeout) Sets and validates the sharding keys for this connection.

Methods inherited from interface javax.sql.PooledConnection

addConnectionEventListener, addStatementEventListener, close, getConnection, removeConnectionEventListener, removeStatementEventListener

Method Detail

getXAResource

XAResource getXAResource()
                  throws SQLException

Retrieves an XAResource object that the transaction manager will use to manage this XAConnection object's participation in a distributed transaction.

Returns:

the XAResource object

Throws:

SQLException - if a database access error occurs

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

Since:

1.4

setShardingKeyIfValid

default boolean setShardingKeyIfValid(ShardingKey shardingKey,
                                      ShardingKey superShardingKey,
                                      int timeout)
                               throws SQLException

Sets and validates the sharding keys for this connection.

API Note:

This method validates that the sharding keys are valid for the Connection. The timeout value indicates how long the driver should wait for the Connection to verify that the sharding key is valid before setShardingKeyIfValid returns false.

Implementation Requirements:

The default implementation will throw a SQLFeatureNotSupportedException.

Parameters:

shardingKey - the sharding key to be validated against this connection

superShardingKey - the super sharding key to be validated against this connection. The super sharding key may be null.

timeout - time in seconds before which the validation process is expected to be completed, otherwise the validation process is aborted. A value of 0 indicates the validation process will not time out.

Returns:

true if the connection is valid and the sharding keys are valid and set on this connection; false if the sharding keys are not valid or the timeout period expires before the operation completes.

Throws:

SQLException - if an error occurs while performing this validation; the shardingkey is null; a superSharedingKey is specified without a shardingKey; this method is called on a closed connection; or the timeout value is less than 0.

SQLFeatureNotSupportedException - if the driver does not support sharding

Since:

1.9

See Also:

ShardingKey, ShardingKeyBuilder

setShardingKeyIfValid

default boolean setShardingKeyIfValid(ShardingKey shardingKey,
                                      int timeout)
                               throws SQLException

Sets and validates the sharding key for this connection.

API Note:

This method validates that the sharding key is valid for the Connection. The timeout value indicates how long the driver should wait for the Connection to verify that the sharding key is valid before setShardingKeyIfValid returns false.

Implementation Requirements:

The default implementation will throw a SQLFeatureNotSupportedException.

Parameters:

shardingKey - the sharding key to be validated against this connection

timeout - time in seconds before which the validation process is expected to be completed,else the validation process is aborted. A value of 0 indicates the validation process will not time out.

Returns:

true if the connection is valid and the sharding key is valid to be set on this connection; false if the sharding key is not valid or the timeout period expires before the operation completes.

Throws:

SQLException - if there is an error while performing this validation; this method is called on a closed connection; the shardingkey is null; or the timeout value is less than 0.

SQLFeatureNotSupportedException - if the driver does not support sharding

Since:

1.9

See Also:

ShardingKey, ShardingKeyBuilder

setShardingKey

default void setShardingKey(ShardingKey shardingKey,
                            ShardingKey superShardingKey)
                     throws SQLException

Specifies a shardingKey and superShardingKey to use with this Connection

API Note:

This method sets the specified sharding keys but does not require a round trip to the database to validate that the sharding keys are valid for the Connection.

Implementation Requirements:

The default implementation will throw a SQLFeatureNotSupportedException.

Parameters:

shardingKey - the sharding key to set on this connection.

superShardingKey - the super sharding key to set on this connection. The super sharding key may be null

Throws:

SQLException - if an error occurs setting the sharding keys; this method is called on a closed connection; the shardingkey is null; or a superSharedingKey is specified without a shardingKey

SQLFeatureNotSupportedException - if the driver does not support sharding

Since:

1.9

See Also:

ShardingKey, ShardingKeyBuilder

setShardingKey

default void setShardingKey(ShardingKey shardingKey)
                     throws SQLException

Specifies a shardingKey to use with this Connection

API Note:

This method sets the specified sharding key but does not require a round trip to the database to validate that the sharding key is valid for the Connection.

Implementation Requirements:

The default implementation will throw a SQLFeatureNotSupportedException.

Parameters:

shardingKey - the sharding key to set on this connection.

Throws:

SQLException - if an error occurs setting the sharding key; this method is called on a closed connection; or the shardkingKey is null

SQLFeatureNotSupportedException - if the driver does not support sharding

Since:

1.9

See Also:

ShardingKey, ShardingKeyBuilder