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
`static interface` `ConnectionFactoryUtils.ResourceFactory` Callback interface for resource creation.

### Constructor Summary

Constructors
Constructor and Description
`ConnectionFactoryUtils()`

### Method Summary

Methods
`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