ConnectionFactoryUtils (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jca.cci.connection

## Class ConnectionFactoryUtils

- java.lang.Object
- - org.springframework.jca.cci.connection.ConnectionFactoryUtils

-     public abstract class ConnectionFactoryUtils
      extends Object

  Helper class that provides static methods for obtaining CCI Connections from a `ConnectionFactory`. Includes special support for Spring-managed transactional Connections, e.g. managed by `CciLocalTransactionManager` or `JtaTransactionManager`.

  Used internally by `CciTemplate`, Spring's CCI operation objects and the `CciLocalTransactionManager`. Can also be used directly in application code.

  Since:
    1.2
  Author:
    Thierry Templier, Juergen Hoeller
  See Also:
    `getConnection(javax.resource.cci.ConnectionFactory)`, `releaseConnection(javax.resource.cci.Connection, javax.resource.cci.ConnectionFactory)`, `CciLocalTransactionManager`, `JtaTransactionManager`, `TransactionSynchronizationManager`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConnectionFactoryUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Connection` | `doGetConnection(ConnectionFactory cf)` Actually obtain a CCI Connection from the given ConnectionFactory.
    `static void` | `doReleaseConnection(Connection con, ConnectionFactory cf)` Actually close the given Connection, obtained from the given ConnectionFactory.
    `static Connection` | `getConnection(ConnectionFactory cf)` Obtain a Connection from the given ConnectionFactory.
    `static Connection` | `getConnection(ConnectionFactory cf, ConnectionSpec spec)` Obtain a Connection from the given ConnectionFactory.
    `static boolean` | `isConnectionTransactional(Connection con, ConnectionFactory cf)` Determine whether the given JCA CCI Connection is transactional, that is, bound to the current thread by Spring's transaction facilities.
    `static void` | `releaseConnection(Connection con, ConnectionFactory cf)` Close the given Connection, obtained from the given ConnectionFactory, if it is not managed externally (that is, not bound to the thread).

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ConnectionFactoryUtils

          public ConnectionFactoryUtils()

  - ### Method Detail

    - #### getConnection

          public static Connection getConnection(ConnectionFactory cf)
                                          throws CannotGetCciConnectionException

      Obtain a Connection from the given ConnectionFactory. Translates ResourceExceptions into the Spring hierarchy of unchecked generic data access exceptions, simplifying calling code and making any exception that is thrown more meaningful.

      Is aware of a corresponding Connection bound to the current thread, for example when using `CciLocalTransactionManager`. Will bind a Connection to the thread if transaction synchronization is active (e.g. if in a JTA transaction).

      Parameters:
        `cf` - the ConnectionFactory to obtain Connection from
      Returns:
        a CCI Connection from the given ConnectionFactory
      Throws:
        `CannotGetCciConnectionException` - if the attempt to get a Connection failed
      See Also:
        `releaseConnection(javax.resource.cci.Connection, javax.resource.cci.ConnectionFactory)`

    - #### getConnection

          public static Connection getConnection(ConnectionFactory cf,
                                 ConnectionSpec spec)
                                          throws CannotGetCciConnectionException

      Obtain a Connection from the given ConnectionFactory. Translates ResourceExceptions into the Spring hierarchy of unchecked generic data access exceptions, simplifying calling code and making any exception that is thrown more meaningful.

      Is aware of a corresponding Connection bound to the current thread, for example when using `CciLocalTransactionManager`. Will bind a Connection to the thread if transaction synchronization is active (e.g. if in a JTA transaction).

      Parameters:
        `cf` - the ConnectionFactory to obtain Connection from
        `spec` - the ConnectionSpec for the desired Connection (may be `null`). Note: If this is specified, a new Connection will be obtained for every call, without participating in a shared transactional Connection.
      Returns:
        a CCI Connection from the given ConnectionFactory
      Throws:
        `CannotGetCciConnectionException` - if the attempt to get a Connection failed
      See Also:
        `releaseConnection(javax.resource.cci.Connection, javax.resource.cci.ConnectionFactory)`

    - #### doGetConnection

          public static Connection doGetConnection(ConnectionFactory cf)
                                            throws ResourceException

      Actually obtain a CCI Connection from the given ConnectionFactory. Same as `getConnection(javax.resource.cci.ConnectionFactory)`, but throwing the original ResourceException.

      Is aware of a corresponding Connection bound to the current thread, for example when using `CciLocalTransactionManager`. Will bind a Connection to the thread if transaction synchronization is active (e.g. if in a JTA transaction).

      Directly accessed by `TransactionAwareConnectionFactoryProxy`.

      Parameters:
        `cf` - the ConnectionFactory to obtain Connection from
      Returns:
        a CCI Connection from the given ConnectionFactory
      Throws:
        `ResourceException` - if thrown by CCI API methods
      See Also:
        `doReleaseConnection(javax.resource.cci.Connection, javax.resource.cci.ConnectionFactory)`

    - #### isConnectionTransactional

          public static boolean isConnectionTransactional(Connection con,
                                          ConnectionFactory cf)

      Determine whether the given JCA CCI Connection is transactional, that is, bound to the current thread by Spring's transaction facilities.
      Parameters:
        `con` - the Connection to check
        `cf` - the ConnectionFactory that the Connection was obtained from (may be `null`)
      Returns:
        whether the Connection is transactional

    - #### releaseConnection

          public static void releaseConnection(Connection con,
                               ConnectionFactory cf)

      Close the given Connection, obtained from the given ConnectionFactory, if it is not managed externally (that is, not bound to the thread).
      Parameters:
        `con` - the Connection to close if necessary (if this is `null`, the call will be ignored)
        `cf` - the ConnectionFactory that the Connection was obtained from (can be `null`)
      See Also:
        `getConnection(javax.resource.cci.ConnectionFactory)`

    - #### doReleaseConnection

          public static void doReleaseConnection(Connection con,
                                 ConnectionFactory cf)
                                          throws ResourceException

      Actually close the given Connection, obtained from the given ConnectionFactory. Same as `releaseConnection(javax.resource.cci.Connection, javax.resource.cci.ConnectionFactory)`, but throwing the original ResourceException.

      Directly accessed by `TransactionAwareConnectionFactoryProxy`.

      Parameters:
        `con` - the Connection to close if necessary (if this is `null`, the call will be ignored)
        `cf` - the ConnectionFactory that the Connection was obtained from (can be `null`)
      Throws:
        `ResourceException` - if thrown by JCA CCI methods
      See Also:
        `doGetConnection(javax.resource.cci.ConnectionFactory)`