public class

SingleConnectionFactory

extends Object
implements DisposableBean InitializingBean
java.lang.Object
   ↳ org.springframework.jms.connection.SingleConnectionFactory
Known Direct Subclasses

Class Overview

A JMS ConnectionFactory adapter that returns the same Connection from all createConnection() calls, and ignores calls to javax.jms.Connection#close(). According to the JMS Connection model, this is perfectly thread-safe (in contrast to e.g. JDBC). The shared Connection can be automatically recovered in case of an Exception.

You can either pass in a specific JMS Connection directly or let this factory lazily create a Connection via a given target ConnectionFactory. This factory generally works with JMS 1.1 as well as the JMS 1.0.2 API.

Note that when using the JMS 1.0.2 API, this ConnectionFactory will switch into queue/topic mode according to the JMS API methods used at runtime: createQueueConnection and createTopicConnection will lead to queue/topic mode, respectively; generic createConnection calls will lead to a JMS 1.1 connection which is able to serve both modes.

Useful for testing and standalone environments in order to keep using the same Connection for multiple JmsTemplate calls, without having a pooling ConnectionFactory underneath. This may span any number of transactions, even concurrently executing transactions.

Note that Spring's message listener containers support the use of a shared Connection within each listener container instance. Using SingleConnectionFactory in combination only really makes sense for sharing a single JMS Connection across multiple listener containers.

See Also

Summary

Fields
protected final Log logger
Public Constructors
SingleConnectionFactory()
Create a new SingleConnectionFactory for bean-style usage.
SingleConnectionFactory(Connection target)
Create a new SingleConnectionFactory that always returns the given Connection.
SingleConnectionFactory(ConnectionFactory targetConnectionFactory)
Create a new SingleConnectionFactory that always returns a single Connection that it will lazily create via the given target ConnectionFactory.
Public Methods
void afterPropertiesSet()
Make sure a Connection or ConnectionFactory has been set.
Connection createConnection()
Connection createConnection(String username, String password)
QueueConnection createQueueConnection(String username, String password)
QueueConnection createQueueConnection()
TopicConnection createTopicConnection()
TopicConnection createTopicConnection(String username, String password)
void destroy()
Close the underlying shared connection.
ConnectionFactory getTargetConnectionFactory()
Return the target ConnectionFactory which will be used to lazily create a single Connection, if any.
void initConnection()
Initialize the underlying shared Connection.
void onException(JMSException ex)
Exception listener callback that renews the underlying single Connection.
void resetConnection()
Reset the underlying shared Connection, to be reinitialized on next access.
void setClientId(String clientId)
Specify a JMS client ID for the single Connection created and exposed by this ConnectionFactory.
void setExceptionListener(ExceptionListener exceptionListener)
Specify an JMS ExceptionListener implementation that should be registered with with the single Connection created by this factory.
void setReconnectOnException(boolean reconnectOnException)
Specify whether the single Connection should be reset (to be subsequently renewed) when a JMSException is reported by the underlying Connection.
void setTargetConnectionFactory(ConnectionFactory targetConnectionFactory)
Set the target ConnectionFactory which will be used to lazily create a single Connection.
Protected Methods
void closeConnection(Connection con)
Close the given Connection.
Session createSession(Connection con, Integer mode)
Create a default Session for this ConnectionFactory, adaptign to JMS 1.0.2 style queue/topic mode if necessary.
Connection doCreateConnection()
Create a JMS Connection via this template's ConnectionFactory.
String getClientId()
Return a JMS client ID for the single Connection created and exposed by this ConnectionFactory, if any.
ExceptionListener getExceptionListener()
Return the JMS ExceptionListener implementation that should be registered with with the single Connection created by this factory, if any.
Session getSession(Connection con, Integer mode)
Template method for obtaining a (potentially cached) Session.
Connection getSharedConnectionProxy(Connection target)
Wrap the given Connection with a proxy that delegates every method call to it but suppresses close calls.
boolean isReconnectOnException()
Return whether the single Connection should be renewed when a JMSException is reported by the underlying Connection.
void prepareConnection(Connection con)
Prepare the given Connection before it is exposed.
[Expand]
Inherited Methods
From class java.lang.Object
From interface org.springframework.beans.factory.DisposableBean
From interface org.springframework.beans.factory.InitializingBean

Fields

protected final Log logger

Public Constructors

public SingleConnectionFactory ()

Create a new SingleConnectionFactory for bean-style usage.

See Also

public SingleConnectionFactory (Connection target)

Create a new SingleConnectionFactory that always returns the given Connection.

Parameters
target the single Connection

public SingleConnectionFactory (ConnectionFactory targetConnectionFactory)

Create a new SingleConnectionFactory that always returns a single Connection that it will lazily create via the given target ConnectionFactory.

Parameters
targetConnectionFactory the target ConnectionFactory

Public Methods

public void afterPropertiesSet ()

Make sure a Connection or ConnectionFactory has been set.

public Connection createConnection ()

Throws
JMSException

public Connection createConnection (String username, String password)

Throws
JMSException

public QueueConnection createQueueConnection (String username, String password)

Throws
JMSException

public QueueConnection createQueueConnection ()

Throws
JMSException

public TopicConnection createTopicConnection ()

Throws
JMSException

public TopicConnection createTopicConnection (String username, String password)

Throws
JMSException

public void destroy ()

Close the underlying shared connection. The provider of this ConnectionFactory needs to care for proper shutdown.

As this bean implements DisposableBean, a bean factory will automatically invoke this on destruction of its cached singletons.

public ConnectionFactory getTargetConnectionFactory ()

Return the target ConnectionFactory which will be used to lazily create a single Connection, if any.

public void initConnection ()

Initialize the underlying shared Connection.

Closes and reinitializes the Connection if an underlying Connection is present already.

Throws
if thrown by JMS API methods
JMSException

public void onException (JMSException ex)

Exception listener callback that renews the underlying single Connection.

public void resetConnection ()

Reset the underlying shared Connection, to be reinitialized on next access.

public void setClientId (String clientId)

Specify a JMS client ID for the single Connection created and exposed by this ConnectionFactory.

Note that client IDs need to be unique among all active Connections of the underlying JMS provider. Furthermore, a client ID can only be assigned if the original ConnectionFactory hasn't already assigned one.

See Also

public void setExceptionListener (ExceptionListener exceptionListener)

Specify an JMS ExceptionListener implementation that should be registered with with the single Connection created by this factory.

See Also

public void setReconnectOnException (boolean reconnectOnException)

Specify whether the single Connection should be reset (to be subsequently renewed) when a JMSException is reported by the underlying Connection.

Default is "false". Switch this to "true" to automatically trigger recovery based on your JMS provider's exception notifications.

Internally, this will lead to a special JMS ExceptionListener (this SingleConnectionFactory itself) being registered with the underlying Connection. This can also be combined with a user-specified ExceptionListener, if desired.

See Also

public void setTargetConnectionFactory (ConnectionFactory targetConnectionFactory)

Set the target ConnectionFactory which will be used to lazily create a single Connection.

Protected Methods

protected void closeConnection (Connection con)

Close the given Connection.

Parameters
con the Connection to close

protected Session createSession (Connection con, Integer mode)

Create a default Session for this ConnectionFactory, adaptign to JMS 1.0.2 style queue/topic mode if necessary.

Parameters
con the JMS Connection to operate on
mode the Session acknowledgement mode (Session.TRANSACTED or one of the common modes)
Returns
  • the newly created Session
Throws
if thrown by the JMS API
JMSException

protected Connection doCreateConnection ()

Create a JMS Connection via this template's ConnectionFactory.

Returns
  • the new JMS Connection
Throws
if thrown by JMS API methods
JMSException

protected String getClientId ()

Return a JMS client ID for the single Connection created and exposed by this ConnectionFactory, if any.

protected ExceptionListener getExceptionListener ()

Return the JMS ExceptionListener implementation that should be registered with with the single Connection created by this factory, if any.

protected Session getSession (Connection con, Integer mode)

Template method for obtaining a (potentially cached) Session.

The default implementation always returns null. Subclasses may override this for exposing specific Session handles, possibly delegating to createSession(Connection, Integer) for the creation of raw Session objects that will then get wrapped and returned from here.

Parameters
con the JMS Connection to operate on
mode the Session acknowledgement mode (Session.TRANSACTED or one of the common modes)
Returns
  • the Session to use, or null to indicate creation of a raw standard Session
Throws
if thrown by the JMS API
JMSException

protected Connection getSharedConnectionProxy (Connection target)

Wrap the given Connection with a proxy that delegates every method call to it but suppresses close calls. This is useful for allowing application code to handle a special framework Connection just like an ordinary Connection from a JMS ConnectionFactory.

Parameters
target the original Connection to wrap
Returns
  • the wrapped Connection

protected boolean isReconnectOnException ()

Return whether the single Connection should be renewed when a JMSException is reported by the underlying Connection.

protected void prepareConnection (Connection con)

Prepare the given Connection before it is exposed.

The default implementation applies ExceptionListener and client id. Can be overridden in subclasses.

Parameters
con the Connection to prepare
Throws
if thrown by JMS API methods
JMSException
See Also