org.nuxeo.runtime.api

Class ConnectionHelper

java.lang.Object

org.nuxeo.runtime.api.ConnectionHelper

public class ConnectionHelper
extends Object

This helper provides a way to get a JDBC connection, through getConnection(String), that will return a connection wrapper able to use a shared connection when used in transactional mode and setAutoCommit(false) is called, and otherwise use a normal physical JDBC connection.

The physical connections are created from the datasource configured using the framework property "nuxeo.db.singleDataSource".

This helper is used to implement consistent resource management in a non-XA context. Several users of the shared connection can call setAutoCommit(false) then do transactional work and commit(). Only the commit() of the last user will do an actual commit on the physical connection.

Since:

5.7

Field Summary

Fields

Modifier and Type	Field and Description
static String	EXCLUDE_DS Property holding one ore more datasource names (comma or space separated) for whose connections the single datasource is not used.
static int	MAX_CONNECTION_TRIES Maximum number of time we retry a connection if the server says it's overloaded.
static String	SINGLE_DS Property holding a datasource name to use to replace all database accesses.

Constructor Summary

Constructors

Constructor and Description
ConnectionHelper()

Method Summary

Methods

Modifier and Type	Method and Description
static void	clearConnectionReferences() Clears the remaining connection references for the current thread.
static int	countConnectionReferences() Checks how many references there are to shared connections.
static Connection	getConnection(String dataSourceName) Gets a new reference to the transaction-local JDBC connection for the given dataSource.
static Connection	getConnection(String dataSourceName, boolean noSharing) Gets a new reference to the transaction-local JDBC connection for the given dataSource.
static String	getPseudoDataSourceNameForRepository(String repositoryName) Gets the fake name we use to pass to ConnectionHelper.getConnection, in order for exclusions on these connections to be possible.
static boolean	registerSynchronization(Synchronization sync) If sharing is in effect, registers a synchronization with the current transaction, making sure it runs before the SharedConnectionSynchronization.
static boolean	registerSynchronizationLast(Synchronization sync) If sharing is in effect, registers a synchronization with the current transaction, making sure the Synchronization.afterCompletion(int) method runs after the SharedConnectionSynchronization.
static Connection	unwrap(Connection connection) Tries to unwrap the connection to get the real physical one (returned by the original datasource).
static boolean	useSingleConnection(String dataSourceName) Checks if single transaction-local datasource mode will be used for the given datasource name.

Methods inherited from class java.lang.Object

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

Field Detail

SINGLE_DS

public static final String SINGLE_DS

Property holding a datasource name to use to replace all database accesses.

See Also:

Constant Field Values

EXCLUDE_DS

public static final String EXCLUDE_DS

Property holding one ore more datasource names (comma or space separated) for whose connections the single datasource is not used.

See Also:

Constant Field Values

MAX_CONNECTION_TRIES

public static final int MAX_CONNECTION_TRIES

Maximum number of time we retry a connection if the server says it's overloaded.

See Also:

Constant Field Values

Constructor Detail

ConnectionHelper

public ConnectionHelper()

Method Detail

unwrap

public static Connection unwrap(Connection connection)
                         throws SQLException

Tries to unwrap the connection to get the real physical one (returned by the original datasource).

This should only be used by code that needs to cast the connection to a driver-specific class to use driver-specific features.

Throws:

SQLException - if no actual physical connection was allocated yet

useSingleConnection

public static boolean useSingleConnection(String dataSourceName)

Checks if single transaction-local datasource mode will be used for the given datasource name.

Returns:

true if using a single transaction-local connection for this datasource

getPseudoDataSourceNameForRepository

public static String getPseudoDataSourceNameForRepository(String repositoryName)

Gets the fake name we use to pass to ConnectionHelper.getConnection, in order for exclusions on these connections to be possible.

getConnection

public static Connection getConnection(String dataSourceName)
                                throws SQLException

Gets a new reference to the transaction-local JDBC connection for the given dataSource. The connection MUST be closed in a finally block when code is done using it.

If the passed dataSource name is in the exclusion list, null will be returned.

Parameters:

dataSourceName - the datasource for which the connection is requested

Returns:

a new reference to the connection, or null if single datasource connection sharing is not in effect

Throws:

SQLException

getConnection

public static Connection getConnection(String dataSourceName,
                       boolean noSharing)
                                throws SQLException

Gets a new reference to the transaction-local JDBC connection for the given dataSource. The connection MUST be closed in a finally block when code is done using it.

If the passed dataSource name is in the exclusion list, null will be returned.

If noSharing is requested, the connection will never come from the transaction-local and will always be newly allocated.

Parameters:

dataSourceName - the datasource for which the connection is requested

noSharing - true if this connection must not be shared with others

Returns:

a new reference to the connection, or null if single datasource connection sharing is not in effect

Throws:

SQLException

countConnectionReferences

public static int countConnectionReferences()

Checks how many references there are to shared connections.

USED IN UNIT TESTS OR FOR DEBUGGING.

clearConnectionReferences

public static void clearConnectionReferences()

Clears the remaining connection references for the current thread.

USED IN UNIT TESTS ONLY.

registerSynchronization

public static boolean registerSynchronization(Synchronization sync)
                                       throws SystemException

If sharing is in effect, registers a synchronization with the current transaction, making sure it runs before the SharedConnectionSynchronization.

Returns:

true

Throws:

SystemException

registerSynchronizationLast

public static boolean registerSynchronizationLast(Synchronization sync)
                                           throws SystemException

If sharing is in effect, registers a synchronization with the current transaction, making sure the Synchronization.afterCompletion(int) method runs after the SharedConnectionSynchronization.

Returns:

true

Throws:

SystemException