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

org.springframework.jms.connection

## Class ConnectionFactoryUtils

- java.lang.Object
- - org.springframework.jms.connection.ConnectionFactoryUtils

-     public abstract class ConnectionFactoryUtils
      extends Object

  Helper class for managing a JMS `ConnectionFactory`, in particular for obtaining transactional JMS resources for a given ConnectionFactory.

  Mainly for internal use within the framework. Used by `JmsTemplate` as well as `DefaultMessageListenerContainer`.

  Since:
    2.0
  Author:
    Juergen Hoeller
  See Also:
    `SmartConnectionFactory`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ConnectionFactoryUtils.ResourceFactory` Callback interface for resource creation.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConnectionFactoryUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Session` | `doGetTransactionalSession(ConnectionFactory connectionFactory, ConnectionFactoryUtils.ResourceFactory resourceFactory)` Obtain a JMS Session that is synchronized with the current transaction, if any.
    `static Session` | `doGetTransactionalSession(ConnectionFactory connectionFactory, ConnectionFactoryUtils.ResourceFactory resourceFactory, boolean startConnection)` Obtain a JMS Session that is synchronized with the current transaction, if any.
    `static Session` | `getTargetSession(Session session)` Return the innermost target Session of the given Session.
    `static QueueSession` | `getTransactionalQueueSession(QueueConnectionFactory cf, QueueConnection existingCon, boolean synchedLocalTransactionAllowed)` Obtain a JMS QueueSession that is synchronized with the current transaction, if any.
    `static Session` | `getTransactionalSession(ConnectionFactory cf, Connection existingCon, boolean synchedLocalTransactionAllowed)` Obtain a JMS Session that is synchronized with the current transaction, if any.
    `static TopicSession` | `getTransactionalTopicSession(TopicConnectionFactory cf, TopicConnection existingCon, boolean synchedLocalTransactionAllowed)` Obtain a JMS TopicSession that is synchronized with the current transaction, if any.
    `static boolean` | `isSessionTransactional(Session session, ConnectionFactory cf)` Determine whether the given JMS Session is transactional, that is, bound to the current thread by Spring's transaction facilities.
    `static void` | `releaseConnection(Connection con, ConnectionFactory cf, boolean started)` Release the given Connection, stopping it (if necessary) and eventually closing it.

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

    - #### releaseConnection

          public static void releaseConnection(Connection con,
                               ConnectionFactory cf,
                               boolean started)

      Release the given Connection, stopping it (if necessary) and eventually closing it.

      Checks `SmartConnectionFactory.shouldStop(javax.jms.Connection)`, if available. This is essentially a more sophisticated version of `JmsUtils.closeConnection(javax.jms.Connection)`.

      Parameters:
        `con` - the Connection to release (if this is `null`, the call will be ignored)
        `cf` - the ConnectionFactory that the Connection was obtained from (may be `null`)
        `started` - whether the Connection might have been started by the application
      See Also:
        `SmartConnectionFactory.shouldStop(javax.jms.Connection)`, `JmsUtils.closeConnection(javax.jms.Connection)`

    - #### getTargetSession

          public static Session getTargetSession(Session session)

      Return the innermost target Session of the given Session. If the given Session is a proxy, it will be unwrapped until a non-proxy Session is found. Otherwise, the passed-in Session will be returned as-is.
      Parameters:
        `session` - the Session proxy to unwrap
      Returns:
        the innermost target Session, or the passed-in one if no proxy
      See Also:
        `SessionProxy.getTargetSession()`

    - #### isSessionTransactional

          public static boolean isSessionTransactional(Session session,
                                       ConnectionFactory cf)

      Determine whether the given JMS Session is transactional, that is, bound to the current thread by Spring's transaction facilities.
      Parameters:
        `session` - the JMS Session to check
        `cf` - the JMS ConnectionFactory that the Session originated from
      Returns:
        whether the Session is transactional

    - #### getTransactionalSession

          public static Session getTransactionalSession(ConnectionFactory cf,
                                        Connection existingCon,
                                        boolean synchedLocalTransactionAllowed)
                                                 throws JMSException

      Obtain a JMS Session that is synchronized with the current transaction, if any.
      Parameters:
        `cf` - the ConnectionFactory to obtain a Session for
        `existingCon` - the existing JMS Connection to obtain a Session for (may be `null`)
        `synchedLocalTransactionAllowed` - whether to allow for a local JMS transaction that is synchronized with a Spring-managed transaction (where the main transaction might be a JDBC-based one for a specific DataSource, for example), with the JMS transaction committing right after the main transaction. If not allowed, the given ConnectionFactory needs to handle transaction enlistment underneath the covers.
      Returns:
        the transactional Session, or `null` if none found
      Throws:
        `JMSException` - in case of JMS failure

    - #### getTransactionalQueueSession

          public static QueueSession getTransactionalQueueSession(QueueConnectionFactory cf,
                                                  QueueConnection existingCon,
                                                  boolean synchedLocalTransactionAllowed)
                                                           throws JMSException

      Obtain a JMS QueueSession that is synchronized with the current transaction, if any.

      Mainly intended for use with the JMS 1.0.2 API.

      Parameters:
        `cf` - the ConnectionFactory to obtain a Session for
        `existingCon` - the existing JMS Connection to obtain a Session for (may be `null`)
        `synchedLocalTransactionAllowed` - whether to allow for a local JMS transaction that is synchronized with a Spring-managed transaction (where the main transaction might be a JDBC-based one for a specific DataSource, for example), with the JMS transaction committing right after the main transaction. If not allowed, the given ConnectionFactory needs to handle transaction enlistment underneath the covers.
      Returns:
        the transactional Session, or `null` if none found
      Throws:
        `JMSException` - in case of JMS failure

    - #### getTransactionalTopicSession

          public static TopicSession getTransactionalTopicSession(TopicConnectionFactory cf,
                                                  TopicConnection existingCon,
                                                  boolean synchedLocalTransactionAllowed)
                                                           throws JMSException

      Obtain a JMS TopicSession that is synchronized with the current transaction, if any.

      Mainly intended for use with the JMS 1.0.2 API.

      Parameters:
        `cf` - the ConnectionFactory to obtain a Session for
        `existingCon` - the existing JMS Connection to obtain a Session for (may be `null`)
        `synchedLocalTransactionAllowed` - whether to allow for a local JMS transaction that is synchronized with a Spring-managed transaction (where the main transaction might be a JDBC-based one for a specific DataSource, for example), with the JMS transaction committing right after the main transaction. If not allowed, the given ConnectionFactory needs to handle transaction enlistment underneath the covers.
      Returns:
        the transactional Session, or `null` if none found
      Throws:
        `JMSException` - in case of JMS failure

    - #### doGetTransactionalSession

          public static Session doGetTransactionalSession(ConnectionFactory connectionFactory,
                                          ConnectionFactoryUtils.ResourceFactory resourceFactory)
                                                   throws JMSException

      Obtain a JMS Session that is synchronized with the current transaction, if any.

      This `doGetTransactionalSession` variant always starts the underlying JMS Connection, assuming that the Session will be used for receiving messages.

      Parameters:
        `connectionFactory` - the JMS ConnectionFactory to bind for (used as TransactionSynchronizationManager key)
        `resourceFactory` - the ResourceFactory to use for extracting or creating JMS resources
      Returns:
        the transactional Session, or `null` if none found
      Throws:
        `JMSException` - in case of JMS failure
      See Also:
        `doGetTransactionalSession(javax.jms.ConnectionFactory, ResourceFactory, boolean)`

    - #### doGetTransactionalSession

          public static Session doGetTransactionalSession(ConnectionFactory connectionFactory,
                                          ConnectionFactoryUtils.ResourceFactory resourceFactory,
                                          boolean startConnection)
                                                   throws JMSException

      Obtain a JMS Session that is synchronized with the current transaction, if any.
      Parameters:
        `connectionFactory` - the JMS ConnectionFactory to bind for (used as TransactionSynchronizationManager key)
        `resourceFactory` - the ResourceFactory to use for extracting or creating JMS resources
        `startConnection` - whether the underlying JMS Connection approach should be started in order to allow for receiving messages. Note that a reused Connection may already have been started before, even if this flag is `false`.
      Returns:
        the transactional Session, or `null` if none found
      Throws:
        `JMSException` - in case of JMS failure