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

org.springframework.jca.cci.connection

## Class TransactionAwareConnectionFactoryProxy

- java.lang.Object
- - org.springframework.jca.cci.connection.DelegatingConnectionFactory
  - - org.springframework.jca.cci.connection.TransactionAwareConnectionFactoryProxy

- All Implemented Interfaces:
    Serializable, Referenceable, ConnectionFactory, InitializingBean

      public class TransactionAwareConnectionFactoryProxy
      extends DelegatingConnectionFactory

  Proxy for a target CCI `ConnectionFactory`, adding awareness of Spring-managed transactions. Similar to a transactional JNDI ConnectionFactory as provided by a J2EE server.

  Data access code that should remain unaware of Spring's data access support can work with this proxy to seamlessly participate in Spring-managed transactions. Note that the transaction manager, for example the `CciLocalTransactionManager`, still needs to work with underlying ConnectionFactory, not with this proxy.

  Make sure that TransactionAwareConnectionFactoryProxy is the outermost ConnectionFactory of a chain of ConnectionFactory proxies/adapters. TransactionAwareConnectionFactoryProxy can delegate either directly to the target connection pool or to some intermediate proxy/adapter like `ConnectionSpecConnectionFactoryAdapter`.

  Delegates to `ConnectionFactoryUtils` for automatically participating in thread-bound transactions, for example managed by `CciLocalTransactionManager`. `getConnection` calls and `close` calls on returned Connections will behave properly within a transaction, i.e. always operate on the transactional Connection. If not within a transaction, normal ConnectionFactory behavior applies.

  This proxy allows data access code to work with the plain JCA CCI API and still participate in Spring-managed transactions, similar to CCI code in a J2EE/JTA environment. However, if possible, use Spring's ConnectionFactoryUtils, CciTemplate or CCI operation objects to get transaction participation even without a proxy for the target ConnectionFactory, avoiding the need to define such a proxy in the first place.

  NOTE: This ConnectionFactory proxy needs to return wrapped Connections in order to handle close calls properly. Therefore, the returned Connections cannot be cast to a native CCI Connection type or to a connection pool implementation type.

  Since:
    1.2
  Author:
    Juergen Hoeller
  See Also:
    `ConnectionFactory.getConnection()`, `Connection.close()`, `ConnectionFactoryUtils.doGetConnection(javax.resource.cci.ConnectionFactory)`, `ConnectionFactoryUtils.doReleaseConnection(javax.resource.cci.Connection, javax.resource.cci.ConnectionFactory)`, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TransactionAwareConnectionFactoryProxy()` Create a new TransactionAwareConnectionFactoryProxy.
    `TransactionAwareConnectionFactoryProxy(ConnectionFactory targetConnectionFactory)` Create a new TransactionAwareConnectionFactoryProxy.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Connection` | `getConnection()` Delegate to ConnectionFactoryUtils for automatically participating in Spring-managed transactions.
    `protected Connection` | `getTransactionAwareConnectionProxy(Connection target, ConnectionFactory cf)` Wrap the given Connection with a proxy that delegates every method call to it but delegates `close` calls to ConnectionFactoryUtils.

    - ### Methods inherited from class org.springframework.jca.cci.connection.DelegatingConnectionFactory

      `afterPropertiesSet, getConnection, getMetaData, getRecordFactory, getReference, getTargetConnectionFactory, setReference, setTargetConnectionFactory`

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

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

- - ### Constructor Detail

    - #### TransactionAwareConnectionFactoryProxy

          public TransactionAwareConnectionFactoryProxy()

      Create a new TransactionAwareConnectionFactoryProxy.
      See Also:
        `DelegatingConnectionFactory.setTargetConnectionFactory(javax.resource.cci.ConnectionFactory)`

    - #### TransactionAwareConnectionFactoryProxy

          public TransactionAwareConnectionFactoryProxy(ConnectionFactory targetConnectionFactory)

      Create a new TransactionAwareConnectionFactoryProxy.
      Parameters:
        `targetConnectionFactory` - the target ConnectionFactory

  - ### Method Detail

    - #### getConnection

          public Connection getConnection()
                                   throws ResourceException

      Delegate to ConnectionFactoryUtils for automatically participating in Spring-managed transactions. Throws the original ResourceException, if any.
      Specified by:
        `getConnection` in interface `ConnectionFactory`
      Overrides:
        `getConnection` in class `DelegatingConnectionFactory`
      Returns:
        a transactional Connection if any, a new one else
      Throws:
        `ResourceException`
      See Also:
        `ConnectionFactoryUtils.doGetConnection(javax.resource.cci.ConnectionFactory)`

    - #### getTransactionAwareConnectionProxy

          protected Connection getTransactionAwareConnectionProxy(Connection target,
                                                      ConnectionFactory cf)

      Wrap the given Connection with a proxy that delegates every method call to it but delegates `close` calls to ConnectionFactoryUtils.
      Parameters:
        `target` - the original Connection to wrap
        `cf` - ConnectionFactory that the Connection came from
      Returns:
        the wrapped Connection
      See Also:
        `Connection.close()`, `ConnectionFactoryUtils.doReleaseConnection(javax.resource.cci.Connection, javax.resource.cci.ConnectionFactory)`