org.springframework.jms.connection

Class SingleConnectionFactory

java.lang.Object

org.springframework.jms.connection.SingleConnectionFactory

All Implemented Interfaces:

DisposableBean, InitializingBean

Direct Known Subclasses:

CachingConnectionFactory

public class SingleConnectionFactory
extends java.lang.Object
implements InitializingBean, DisposableBean

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.

Since:

1.1

Author:

Juergen Hoeller, Mark Pollack

See Also:

JmsTemplate, SimpleMessageListenerContainer, DefaultMessageListenerContainer.setCacheLevel(int)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	SingleConnectionFactory.AggregatedExceptionListener Internal aggregated ExceptionListener for handling the internal recovery listener in combination with user-specified listeners.
private class	SingleConnectionFactory.SharedConnectionInvocationHandler Invocation handler for a cached JMS Connection proxy.

Field Summary

Fields

Modifier and Type	Field and Description
private SingleConnectionFactory.AggregatedExceptionListener	aggregatedExceptionListener An internal aggregator allowing for per-connection ExceptionListeners
private java.lang.String	clientId
private Connection	connection The target Connection
private java.lang.Object	connectionMonitor Synchronization monitor for the shared Connection
private ExceptionListener	exceptionListener
protected Log	logger
private java.lang.Boolean	pubSubMode A hint whether to create a queue or topic connection
private boolean	reconnectOnException
private int	startedCount Whether the shared Connection has been started
private ConnectionFactory	targetConnectionFactory

Constructor Summary

Constructors

Constructor and Description
SingleConnectionFactory() Create a new SingleConnectionFactory for bean-style usage.
SingleConnectionFactory(Connection targetConnection) 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.

Method Summary

Modifier and Type	Method and Description
void	afterPropertiesSet() Make sure a Connection or ConnectionFactory has been set.
protected void	closeConnection(Connection con) Close the given Connection.
Connection	createConnection()
Connection	createConnection(java.lang.String username, java.lang.String password)
QueueConnection	createQueueConnection()
QueueConnection	createQueueConnection(java.lang.String username, java.lang.String password)
protected Session	createSession(Connection con, java.lang.Integer mode) Create a default Session for this ConnectionFactory, adapting to JMS 1.0.2 style queue/topic mode if necessary.
TopicConnection	createTopicConnection()
TopicConnection	createTopicConnection(java.lang.String username, java.lang.String password)
void	destroy() Close the underlying shared connection.
protected Connection	doCreateConnection() Create a JMS Connection via this template's ConnectionFactory.
protected java.lang.String	getClientId() Return a JMS client ID for the single Connection created and exposed by this ConnectionFactory, if any.
protected Connection	getConnection() Obtain an initialized shared Connection.
protected ExceptionListener	getExceptionListener() Return the JMS ExceptionListener implementation that should be registered with the single Connection created by this factory, if any.
protected Session	getSession(Connection con, java.lang.Integer mode) Template method for obtaining a (potentially cached) Session.
protected Connection	getSharedConnectionProxy(Connection target) Wrap the given Connection with a proxy that delegates every method call to it but suppresses close calls.
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.
protected boolean	isReconnectOnException() Return whether the single Connection should be renewed when a JMSException is reported by the underlying Connection.
void	onException(JMSException ex) Exception listener callback that renews the underlying single Connection.
protected void	prepareConnection(Connection con) Prepare the given Connection before it is exposed.
void	resetConnection() Reset the underlying shared Connection, to be reinitialized on next access.
void	setClientId(java.lang.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 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.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final Log logger

targetConnectionFactory

private ConnectionFactory targetConnectionFactory

clientId

private java.lang.String clientId

exceptionListener

private ExceptionListener exceptionListener

reconnectOnException

private boolean reconnectOnException

connection

private Connection connection

The target Connection

pubSubMode

private java.lang.Boolean pubSubMode

A hint whether to create a queue or topic connection

aggregatedExceptionListener

private SingleConnectionFactory.AggregatedExceptionListener aggregatedExceptionListener

An internal aggregator allowing for per-connection ExceptionListeners

startedCount

private int startedCount

Whether the shared Connection has been started

connectionMonitor

private final java.lang.Object connectionMonitor

Synchronization monitor for the shared Connection

Constructor Detail

SingleConnectionFactory

public SingleConnectionFactory()

Create a new SingleConnectionFactory for bean-style usage.

See Also:

setTargetConnectionFactory(ConnectionFactory)

SingleConnectionFactory

public SingleConnectionFactory(Connection targetConnection)

Create a new SingleConnectionFactory that always returns the given Connection.

Parameters:

targetConnection - the single Connection

SingleConnectionFactory

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

Method Detail

setTargetConnectionFactory

public void setTargetConnectionFactory(ConnectionFactory targetConnectionFactory)

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

getTargetConnectionFactory

public ConnectionFactory getTargetConnectionFactory()

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

setClientId

public void setClientId(java.lang.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:

javax.jms.Connection#setClientID, setTargetConnectionFactory(ConnectionFactory)

getClientId

protected java.lang.String getClientId()

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

setExceptionListener

public void setExceptionListener(ExceptionListener exceptionListener)

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

See Also:

setReconnectOnException(boolean)

getExceptionListener

protected ExceptionListener getExceptionListener()

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

setReconnectOnException

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:

setExceptionListener(ExceptionListener)

isReconnectOnException

protected boolean isReconnectOnException()

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

afterPropertiesSet

public void afterPropertiesSet()

Make sure a Connection or ConnectionFactory has been set.

Specified by:

afterPropertiesSet in interface InitializingBean

createConnection

public Connection createConnection()
                            throws JMSException

Throws:

JMSException

createConnection

public Connection createConnection(java.lang.String username,
                                   java.lang.String password)
                            throws JMSException

Throws:

JMSException

createQueueConnection

public QueueConnection createQueueConnection()
                                      throws JMSException

Throws:

JMSException

createQueueConnection

public QueueConnection createQueueConnection(java.lang.String username,
                                             java.lang.String password)
                                      throws JMSException

Throws:

JMSException

createTopicConnection

public TopicConnection createTopicConnection()
                                      throws JMSException

Throws:

JMSException

createTopicConnection

public TopicConnection createTopicConnection(java.lang.String username,
                                             java.lang.String password)
                                      throws JMSException

Throws:

JMSException

getConnection

protected Connection getConnection()
                            throws JMSException

Obtain an initialized shared Connection.

Returns:

the Connection (never null)

Throws:

javax.jms.JMSException - if thrown by JMS API methods

JMSException

See Also:

initConnection()

initConnection

public void initConnection()
                    throws JMSException

Initialize the underlying shared Connection.

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

Throws:

javax.jms.JMSException - if thrown by JMS API methods

JMSException

See Also:

prepareConnection(Connection)

onException

public void onException(JMSException ex)

Exception listener callback that renews the underlying single Connection.

See Also:

resetConnection()

destroy

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.

Specified by:

destroy in interface DisposableBean

See Also:

resetConnection()

resetConnection

public void resetConnection()

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

See Also:

closeConnection(Connection)

doCreateConnection

protected Connection doCreateConnection()
                                 throws JMSException

Create a JMS Connection via this template's ConnectionFactory.

Returns:

the new JMS Connection

Throws:

javax.jms.JMSException - if thrown by JMS API methods

JMSException

prepareConnection

protected void prepareConnection(Connection con)
                          throws JMSException

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:

JMSException - if thrown by JMS API methods

See Also:

setExceptionListener(ExceptionListener), setReconnectOnException(boolean)

getSession

protected Session getSession(Connection con,
                             java.lang.Integer mode)
                      throws JMSException

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, java.lang.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:

JMSException - if thrown by the JMS API

createSession

protected Session createSession(Connection con,
                                java.lang.Integer mode)
                         throws JMSException

Create a default Session for this ConnectionFactory, adapting 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:

JMSException - if thrown by the JMS API

closeConnection

protected void closeConnection(Connection con)

Close the given Connection.

Parameters:

con - the Connection to close

getSharedConnectionProxy

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