public class

SimpleMessageListenerContainer

extends AbstractMessageListenerContainer

java.lang.Object
↳	org.springframework.jms.support.JmsAccessor
	↳	org.springframework.jms.support.destination.JmsDestinationAccessor
		↳	org.springframework.jms.listener.AbstractJmsListeningContainer
			↳	org.springframework.jms.listener.AbstractMessageListenerContainer
				↳	org.springframework.jms.listener.SimpleMessageListenerContainer

Known Direct Subclasses

SimpleMessageListenerContainer102

Class Overview

Message listener container that uses the plain JMS client API's MessageConsumer.setMessageListener() method to create concurrent MessageConsumers for the specified listeners.

This is the simplest form of a message listener container. It creates a fixed number of JMS Sessions to invoke the listener, not allowing for dynamic adaptation to runtime demands. Its main advantage is its low level of complexity and the minimum requirements on the JMS provider: Not even the ServerSessionPool facility is required.

See the AbstractMessageListenerContainer javadoc for details on acknowledge modes and transaction options.

For a different style of MessageListener handling, through looped MessageConsumer.receive() calls that also allow for transactional reception of messages (registering them with XA transactions), see DefaultMessageListenerContainer.

Summary

[Expand]

Inherited Fields

From class org.springframework.jms.listener.AbstractJmsListeningContainer

From class org.springframework.jms.support.JmsAccessor

Public Constructors
	SimpleMessageListenerContainer()

Public Methods
void	onException(JMSException ex) JMS ExceptionListener implementation, invoked by the JMS provider in case of connection failures.
void	setConcurrency(String concurrency) Specify concurrency limits via a "lower-upper" String, e.g.
void	setConcurrentConsumers(int concurrentConsumers) Specify the number of concurrent consumers to create.
void	setPubSubNoLocal(boolean pubSubNoLocal) Set whether to inhibit the delivery of messages published by its own connection.
void	setTaskExecutor(Executor taskExecutor) Set the Spring TaskExecutor to use for executing the listener once a message has been received by the provider.

Protected Methods
MessageConsumer	createConsumer(Session session, Destination destination) Create a JMS MessageConsumer for the given Session and Destination.
MessageConsumer	createListenerConsumer(Session session) Create a MessageConsumer for the given JMS Session, registering a MessageListener for the specified listener.
void	doInitialize() Creates the specified number of concurrent consumers, in the form of a JMS Session plus associated MessageConsumer.
void	doShutdown() Destroy the registered JMS Sessions and associated MessageConsumers.
void	doStart() Re-initializes this container's JMS message consumers, if not initialized already.
void	initializeConsumers() Initialize the JMS Sessions and MessageConsumers for this container.
boolean	isPubSubNoLocal() Return whether to inhibit the delivery of messages published by its own connection.
void	prepareSharedConnection(Connection connection) Registers this listener container as JMS ExceptionListener on the shared connection.
void	processMessage(Message message, Session session) Process a message received from the provider.
final boolean	sharedConnectionEnabled() Always use a shared JMS Connection.
void	validateConfiguration() Validate the configuration of this container.

[Expand]

Inherited Methods

From class org.springframework.jms.listener.AbstractMessageListenerContainer

void	checkMessageListener(Object messageListener) Check the given message listener, throwing an exception if it does not correspond to a supported listener type.
void	commitIfNecessary(Session session, Message message) Perform a commit or message acknowledgement, as appropriate.
void	doExecuteListener(Session session, Message message) Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).
void	doInvokeListener(SessionAwareMessageListener listener, Session session, Message message) Invoke the specified listener as Spring SessionAwareMessageListener, exposing a new JMS Session (potentially with its own transaction) to the listener if demanded.
void	doInvokeListener(MessageListener listener, Message message) Invoke the specified listener as standard JMS MessageListener.
void	executeListener(Session session, Message message) Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).
String	getDefaultSubscriptionName(Object messageListener) Determine the default subscription name for the given message listener.
Destination	getDestination() Return the destination to receive messages from.
String	getDestinationDescription() Return a descriptive String for this container's JMS destination (never `null`).
String	getDestinationName() Return the name of the destination to receive messages from.
String	getDurableSubscriptionName() Return the name of a durable subscription to create, if any.
ExceptionListener	getExceptionListener() Return the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure, if any.
Object	getMessageListener() Return the message listener object to register.
String	getMessageSelector() Return the JMS message selector expression (or `null` if none).
void	handleListenerException(Throwable ex) Handle the given exception that arose during listener execution.
void	invokeErrorHandler(Throwable ex) Invoke the registered ErrorHandler, if any.
void	invokeExceptionListener(JMSException ex) Invoke the registered JMS ExceptionListener, if any.
void	invokeListener(Session session, Message message) Invoke the specified listener: either as standard JMS MessageListener or (preferably) as Spring SessionAwareMessageListener.
boolean	isAcceptMessagesWhileStopping() Return whether to accept received messages while the listener container in the process of stopping.
boolean	isExposeListenerSession() Return whether to expose the listener JMS Session to a registered `SessionAwareMessageListener`.
boolean	isSessionLocallyTransacted(Session session) Check whether the given Session is locally transacted, that is, whether its transaction is managed by this listener container's Session handling and not by an external transaction coordinator.
boolean	isSubscriptionDurable() Return whether to make the subscription durable.
void	rollbackIfNecessary(Session session) Perform a rollback, if appropriate.
void	rollbackOnExceptionIfNecessary(Session session, Throwable ex) Perform a rollback, handling rollback exceptions properly.
void	setAcceptMessagesWhileStopping(boolean acceptMessagesWhileStopping) Set whether to accept received messages while the listener container in the process of stopping.
void	setDestination(Destination destination) Set the destination to receive messages from.
void	setDestinationName(String destinationName) Set the name of the destination to receive messages from.
void	setDurableSubscriptionName(String durableSubscriptionName) Set the name of a durable subscription to create.
void	setErrorHandler(ErrorHandler errorHandler) Set an ErrorHandler to be invoked in case of any uncaught exceptions thrown while processing a Message.
void	setExceptionListener(ExceptionListener exceptionListener) Set the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure.
void	setExposeListenerSession(boolean exposeListenerSession) Set whether to expose the listener JMS Session to a registered `SessionAwareMessageListener` as well as to `JmsTemplate` calls.
void	setMessageListener(Object messageListener) Set the message listener implementation to register.
void	setMessageSelector(String messageSelector) Set the JMS message selector expression (or `null` if none).
void	setSubscriptionDurable(boolean subscriptionDurable) Set whether to make the subscription durable.
void	validateConfiguration() Validate the configuration of this container.

From class org.springframework.jms.listener.AbstractJmsListeningContainer

void	afterPropertiesSet() Delegates to `validateConfiguration()` and `initialize()`.
Connection	createSharedConnection() Create a shared Connection for this container.
void	destroy() Calls `shutdown()` when the BeanFactory destroys the container instance.
abstract void	doInitialize() Register any invokers within this container.
void	doRescheduleTask(Object task) Reschedule the given task object immediately.
abstract void	doShutdown() Close the registered invokers.
void	doStart() Start the shared Connection, if any, and notify all invoker tasks.
void	doStop() Notify all invoker tasks and stop the shared Connection, if any.
void	establishSharedConnection() Establish a shared Connection for this container.
final String	getBeanName() Return the bean name that this listener container has been assigned in its containing bean factory, if any.
String	getClientId() Return the JMS client ID for the shared Connection created and used by this container, if any.
int	getPausedTaskCount() Determine the number of currently paused tasks, if any.
int	getPhase() Return the phase in which this container will be started and stopped.
final Connection	getSharedConnection() Return the shared JMS Connection maintained by this container.
void	initialize() Initialize this container.
final boolean	isActive() Return whether this container is currently active, that is, whether it has been set up but not shut down yet.
boolean	isAutoStartup() Return whether this Lifecycle component should be started automatically by the container when the ApplicationContext is refreshed.
final boolean	isRunning() Determine whether this container is currently running, that is, whether it has been started and not stopped yet.
void	logRejectedTask(Object task, RuntimeException ex) Log a task that has been rejected by `doRescheduleTask(Object)`.
void	prepareSharedConnection(Connection connection) Prepare the given Connection, which is about to be registered as shared Connection for this container.
final void	refreshSharedConnection() Refresh the shared Connection that this container holds.
final boolean	rescheduleTaskIfNecessary(Object task) Take the given task object and reschedule it, either immediately if this container is currently running, or later once this container has been restarted.
void	resumePausedTasks() Try to resume all paused tasks.
boolean	runningAllowed() Check whether this container's listeners are generally allowed to run.
void	setAutoStartup(boolean autoStartup) Set whether to automatically start the container after initialization.
void	setBeanName(String beanName) Set the name of the bean in the bean factory that created this bean.
void	setClientId(String clientId) Specify the JMS client id for a shared Connection created and used by this container.
void	setPhase(int phase) Specify the phase in which this container should be started and stopped.
abstract boolean	sharedConnectionEnabled() Return whether a shared JMS Connection should be maintained by this container base class.
void	shutdown() Stop the shared Connection, call `doShutdown()`, and close this container.
void	start() Start this container.
void	startSharedConnection() Start the shared Connection.
void	stop() Stop this container.
void	stop(Runnable callback) Indicates that a Lifecycle component must stop if it is currently running.
void	stopSharedConnection() Stop the shared Connection.
void	validateConfiguration() Validate the configuration of this container.

From class org.springframework.jms.support.destination.JmsDestinationAccessor

From class org.springframework.jms.support.JmsAccessor

void	afterPropertiesSet() Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
JmsException	convertJmsAccessException(JMSException ex) Convert the specified checked javax.jms.JMSException JMSException to a Spring runtime `JmsException` equivalent.
Connection	createConnection() Create a JMS Connection via this template's ConnectionFactory.
Session	createSession(Connection con) Create a JMS Session for the given Connection.
ConnectionFactory	getConnectionFactory() Return the ConnectionFactory that this accessor uses for obtaining JMS Connection Connections.
int	getSessionAcknowledgeMode() Return the acknowledgement mode for JMS Session sessions.
boolean	isClientAcknowledge(Session session) Determine whether the given Session is in client acknowledge mode.
boolean	isSessionTransacted() Return whether the JMS Session sessions used by this accessor are supposed to be transacted.
void	setConnectionFactory(ConnectionFactory connectionFactory) Set the ConnectionFactory to use for obtaining JMS Connection Connections.
void	setSessionAcknowledgeMode(int sessionAcknowledgeMode) Set the JMS acknowledgement mode that is used when creating a JMS Session to send a message.
void	setSessionAcknowledgeModeName(String constantName) Set the JMS acknowledgement mode by the name of the corresponding constant in the JMS Session interface, e.g.
void	setSessionTransacted(boolean sessionTransacted) Set the transaction mode that is used when creating a JMS Session.

From class java.lang.Object

From interface org.springframework.beans.factory.BeanNameAware

From interface org.springframework.beans.factory.DisposableBean

From interface org.springframework.beans.factory.InitializingBean

From interface org.springframework.context.Lifecycle

From interface org.springframework.context.Phased

From interface org.springframework.context.SmartLifecycle

Public Constructors

public SimpleMessageListenerContainer ()

Public Methods

public void onException (JMSException ex)

JMS ExceptionListener implementation, invoked by the JMS provider in case of connection failures. Re-initializes this listener container's shared connection and its sessions and consumers.

Parameters

ex	the reported connection exception

public void setConcurrency (String concurrency)

Specify concurrency limits via a "lower-upper" String, e.g. "5-10", or a simple upper limit String, e.g. "10".

This listener container will always hold on to the maximum number of consumers setConcurrentConsumers(int) since it is unable to scale.

This property is primarily supported for configuration compatibility with DefaultMessageListenerContainer. For this local listener container, generally use setConcurrentConsumers(int) instead.

public void setConcurrentConsumers (int concurrentConsumers)

Specify the number of concurrent consumers to create. Default is 1.

Raising the number of concurrent consumers is recommendable in order to scale the consumption of messages coming in from a queue. However, note that any ordering guarantees are lost once multiple consumers are registered. In general, stick with 1 consumer for low-volume queues.

Do not raise the number of concurrent consumers for a topic. This would lead to concurrent consumption of the same message, which is hardly ever desirable.

public void setPubSubNoLocal (boolean pubSubNoLocal)

Set whether to inhibit the delivery of messages published by its own connection. Default is "false".

public void setTaskExecutor (Executor taskExecutor)

Set the Spring TaskExecutor to use for executing the listener once a message has been received by the provider.

Default is none, that is, to run in the JMS provider's own receive thread, blocking the provider's receive endpoint while executing the listener.

Specify a TaskExecutor for executing the listener in a different thread, rather than blocking the JMS provider, usually integrating with an existing thread pool. This allows to keep the number of concurrent consumers low (1) while still processing messages concurrently (decoupled from receiving!).

NOTE: Specifying a TaskExecutor for listener execution affects acknowledgement semantics. Messages will then always get acknowledged before listener execution, with the underlying Session immediately reused for receiving the next message. Using this in combination with a transacted session or with client acknowledgement will lead to unspecified results!

NOTE: Concurrent listener execution via a TaskExecutor will lead to concurrent processing of messages that have been received by the same underlying Session. As a consequence, it is not recommended to use this setting with a SessionAwareMessageListener, at least not if the latter performs actual work on the given Session. A standard javax.jms.MessageListener will work fine, in general.

Protected Methods

protected MessageConsumer createConsumer (Session session, Destination destination)

Create a JMS MessageConsumer for the given Session and Destination.

This implementation uses JMS 1.1 API.

Parameters

session	the JMS Session to create a MessageConsumer for
destination	the JMS Destination to create a MessageConsumer for

Returns

the new JMS MessageConsumer

Throws

	if thrown by JMS API methods
JMSException

protected MessageConsumer createListenerConsumer (Session session)

Create a MessageConsumer for the given JMS Session, registering a MessageListener for the specified listener.

Parameters

session	the JMS Session to work on

Returns

the MessageConsumer

Throws

	if thrown by JMS methods
JMSException

protected void doInitialize ()

Creates the specified number of concurrent consumers, in the form of a JMS Session plus associated MessageConsumer.

Throws

JMSException

protected void doShutdown ()

Destroy the registered JMS Sessions and associated MessageConsumers.

Throws

JMSException

protected void doStart ()

Re-initializes this container's JMS message consumers, if not initialized already.

Throws

JMSException

protected void initializeConsumers ()

Initialize the JMS Sessions and MessageConsumers for this container.

Throws

	in case of setup failure
JMSException

protected boolean isPubSubNoLocal ()

Return whether to inhibit the delivery of messages published by its own connection.

protected void prepareSharedConnection (Connection connection)

Registers this listener container as JMS ExceptionListener on the shared connection.

Parameters

connection	the Connection to prepare

Throws

JMSException

protected void processMessage (Message message, Session session)

Process a message received from the provider.

Executes the listener, exposing the current JMS Session as thread-bound resource (if "exposeListenerSession" is "true").

Parameters

message	the received JMS Message
session	the JMS Session to operate on

protected final boolean sharedConnectionEnabled ()

Always use a shared JMS Connection.

protected void validateConfiguration ()

Validate the configuration of this container.

The default implementation is empty. To be overridden in subclasses.

Interfaces

Classes

Exceptions

SimpleMessageListenerContainer

Class Overview

See Also

Summary

Public Constructors

public SimpleMessageListenerContainer ()

Public Methods

public void onException (JMSException ex)

Parameters

public void setConcurrency (String concurrency)

public void setConcurrentConsumers (int concurrentConsumers)

public void setPubSubNoLocal (boolean pubSubNoLocal)

See Also

public void setTaskExecutor (Executor taskExecutor)

See Also

Protected Methods

protected MessageConsumer createConsumer (Session session, Destination destination)

Parameters

Returns

Throws

protected MessageConsumer createListenerConsumer (Session session)

Parameters

Returns

Throws

See Also

protected void doInitialize ()

Throws

See Also

protected void doShutdown ()

Throws

protected void doStart ()

Throws

protected void initializeConsumers ()

Throws

protected boolean isPubSubNoLocal ()

protected void prepareSharedConnection (Connection connection)

Parameters

Throws

protected void processMessage (Message message, Session session)

Parameters

See Also

protected final boolean sharedConnectionEnabled ()

protected void validateConfiguration ()