The Spring Framework

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

Constructor Summary
`ConnectionFactoryUtils()`

Method Summary
`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 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)`

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

The Spring Framework

Copyright © 2002-2008 The Spring Framework.