Spring Framework 6.1.4 · org.springframework.jms.connection.SingleConnectionFactory

A JMS ConnectionFactory adapter that returns the same Connection from all createConnection() calls, and ignores calls to jakarta.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.

As of Spring Framework 5, this class supports JMS 2.0 JMSContext calls and therefore requires the JMS 2.0 API to be present at runtime. It may nevertheless run against a JMS 1.1 driver (bound to the JMS 2.0 API) as long as no actual JMS 2.0 calls are triggered by the application's setup.

Useful for testing and standalone environments in order to keep using the same Connection for multiple org.springframework.jms.core.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.

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.

Modifier and Type	Field and Description
private SingleConnectionFactory.AggregatedExceptionListener	aggregatedExceptionListener An internal aggregator allowing for per-connection ExceptionListeners.
private String	clientId
private Connection	connection The target Connection.
private final Object	connectionMonitor Synchronization monitor for the shared Connection.
private ExceptionListener	exceptionListener
protected final Log	logger
private 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

Access	Constructor and Description
public	SingleConnectionFactory() Create a new SingleConnectionFactory for bean-style usage.
public	SingleConnectionFactory(Connection the single Connection targetConnection) Create a new SingleConnectionFactory that always returns the given Connection.
public	SingleConnectionFactory(ConnectionFactory the target 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
public void	afterPropertiesSet() Implements org.springframework.beans.factory.InitializingBean.afterPropertiesSet. Make sure a Connection or ConnectionFactory has been set.
protected void	closeConnection(Connection the Connection to close con) Close the given Connection.
public Connection	createConnection() Implements jakarta.jms.ConnectionFactory.createConnection. Creates a connection with the default user identity.
public Connection	createConnection(String the caller's user name username, String the caller's password password) Implements jakarta.jms.ConnectionFactory.createConnection. Creates a connection with the specified user identity.
public JMSContext	createContext() Implements jakarta.jms.ConnectionFactory.createContext. Creates a JMSContext with the default user identity and an unspecified sessionMode.
public JMSContext	createContext(String the caller's user name userName, String the caller's password password) Implements jakarta.jms.ConnectionFactory.createContext. Creates a JMSContext with the specified user identity and an unspecified sessionMode.
public JMSContext	createContext(String the caller's user name userName, String the caller's password password, int indicates which of four possible session modes will be used. If this method is called in a Java SE environment or in the Jakarta EE application client container, the permitted values are `JMSContext.SESSION_TRANSACTED`, `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`. If this method is called in the Jakarta EE web or EJB container when there is an active JTA transaction in progress then this argument is ignored. If this method is called in the Jakarta EE web or EJB container when there is no active JTA transaction in progress, the permitted values are `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`. In this case the values `JMSContext.TRANSACTED` and `JMSContext.CLIENT_ACKNOWLEDGE` are not permitted. sessionMode) Implements jakarta.jms.ConnectionFactory.createContext. Creates a JMSContext with the specified user identity and the specified session mode.
public JMSContext	createContext(int indicates which of four possible session modes will be used. If this method is called in a Java SE environment or in the Jakarta EE application client container, the permitted values are `JMSContext.SESSION_TRANSACTED`, `JMSContext.CLIENT_ACKNOWLEDGE`, `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`. If this method is called in the Jakarta EE web or EJB container when there is an active JTA transaction in progress then this argument is ignored. If this method is called in the Jakarta EE web or EJB container when there is no active JTA transaction in progress, the permitted values are `JMSContext.AUTO_ACKNOWLEDGE` and `JMSContext.DUPS_OK_ACKNOWLEDGE`. In this case the values `JMSContext.TRANSACTED` and `JMSContext.CLIENT_ACKNOWLEDGE` are not permitted. sessionMode) Implements jakarta.jms.ConnectionFactory.createContext. Creates a JMSContext with the default user identity and the specified session mode.
public QueueConnection	createQueueConnection() Implements jakarta.jms.QueueConnectionFactory.createQueueConnection. Creates a queue connection with the default user identity.
public QueueConnection	createQueueConnection(String the caller's user name username, String the caller's password password) Implements jakarta.jms.QueueConnectionFactory.createQueueConnection. Creates a queue connection with the specified user identity.
protected Session	Returns: the newly created Session createSession(Connection the JMS Connection to operate on con, Integer the Session acknowledgement mode (`Session.TRANSACTED` or one of the common modes) mode) Create a default Session for this ConnectionFactory, adapting to JMS 1.0.2 style queue/topic mode if necessary.
public TopicConnection	createTopicConnection() Implements jakarta.jms.TopicConnectionFactory.createTopicConnection. Creates a topic connection with the default user identity.
public TopicConnection	createTopicConnection(String the caller's user name username, String the caller's password password) Implements jakarta.jms.TopicConnectionFactory.createTopicConnection. Creates a topic connection with the specified user identity.
public void	destroy() Implements org.springframework.beans.factory.DisposableBean.destroy. Close the underlying shared connection.
protected Connection	Returns: the new JMS Connection doCreateConnection() Create a JMS Connection via this template's ConnectionFactory.
protected String	getClientId() Return a JMS client ID for the single Connection created and exposed by this ConnectionFactory, if any.
protected Connection	Returns: the Connection (never `null`) 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	Returns: the Session to use, or `null` to indicate creation of a raw standard Session getSession(Connection the JMS Connection to operate on con, Integer the Session acknowledgement mode (`Session.TRANSACTED` or one of the common modes) mode) Template method for obtaining a (potentially cached) Session.
protected Connection	Returns: the wrapped Connection getSharedConnectionProxy(Connection the original Connection to wrap target) Wrap the given Connection with a proxy that delegates every method call to it but suppresses close calls.
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.
protected boolean	isReconnectOnException() Return whether the single Connection should be renewed when a JMSException is reported by the underlying Connection.
public boolean	isRunning() Implements org.springframework.context.Lifecycle.isRunning. Check whether there is currently an underlying connection.
private ConnectionFactory	obtainTargetConnectionFactory()
public void	onException(JMSException the Jakarta Messaging exception ex) Implements jakarta.jms.ExceptionListener.onException. Exception listener callback that renews the underlying single Connection.
protected void	prepareConnection(Connection the Connection to prepare con) Prepare the given Connection before it is exposed.
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.
public void	setExceptionListener(ExceptionListener exceptionListener) Specify an JMS ExceptionListener implementation that should be registered with the single Connection created by this factory.
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.
public void	setTargetConnectionFactory(ConnectionFactory targetConnectionFactory) Set the target ConnectionFactory which will be used to lazily create a single Connection.
public void	start() Implements org.springframework.context.Lifecycle.start. Initialize the underlying shared connection on start.
public void	stop() Implements org.springframework.context.Lifecycle.stop. Reset the underlying shared connection on stop.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public Class SingleConnectionFactory

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary