Class AbstractMessageListenerContainer
- All Implemented Interfaces:
Aware
,BeanNameAware
,DisposableBean
,InitializingBean
,Lifecycle
,Phased
,SmartLifecycle
,MessageListenerContainer
- Direct Known Subclasses:
AbstractPollingMessageListenerContainer
,SimpleMessageListenerContainer
MessageListener
or Spring's
SessionAwareMessageListener
for actual message processing.
Usually holds a single JMS Connection
that all listeners are supposed
to be registered on, which is the standard JMS way of managing listener sessions.
Can alternatively also be used with a fresh Connection per listener, for Jakarta EE
style XA-aware JMS messaging. The actual registration process is up to concrete
subclasses.
NOTE: The default behavior of this message listener container is to
never propagate an exception thrown by a message listener up to the JMS
provider. Instead, it will log any such exception at WARN
level.
This means that from the perspective of the attendant JMS provider no such
listener will ever fail. However, if error handling is necessary, then
an implementation of the ErrorHandler
strategy may be provided to
the setErrorHandler(ErrorHandler)
method. Note that JMSExceptions
will be passed to the ErrorHandler
in addition to (but after)
being passed to an ExceptionListener
, if one has been provided.
The listener container offers the following message acknowledgment options:
- "sessionAcknowledgeMode" set to "AUTO_ACKNOWLEDGE" (default):
This mode is container-dependent: For
DefaultMessageListenerContainer
, it means automatic message acknowledgment before listener execution, with no redelivery in case of an exception and no redelivery in case of other listener execution interruptions either. ForSimpleMessageListenerContainer
, it means automatic message acknowledgment after listener execution, with no redelivery in case of a user exception thrown but potential redelivery in case of the JVM dying during listener execution. In order to consistently arrange for redelivery with any container variant, consider "CLIENT_ACKNOWLEDGE" mode or - preferably - setting "sessionTransacted" to "true" instead. - "sessionAcknowledgeMode" set to "DUPS_OK_ACKNOWLEDGE":
Lazy message acknowledgment during (
DefaultMessageListenerContainer
) or shortly after (SimpleMessageListenerContainer
) listener execution; no redelivery in case of a user exception thrown but potential redelivery in case of the JVM dying during listener execution. In order to consistently arrange for redelivery with any container variant, consider "CLIENT_ACKNOWLEDGE" mode or - preferably - setting "sessionTransacted" to "true" instead. - "sessionAcknowledgeMode" set to "CLIENT_ACKNOWLEDGE": Automatic message acknowledgment after successful listener execution; best-effort redelivery in case of a user exception thrown as well as in case of other listener execution interruptions (such as the JVM dying).
- "sessionTransacted" set to "true": Transactional acknowledgment after successful listener execution; guaranteed redelivery in case of a user exception thrown as well as in case of other listener execution interruptions (such as the JVM dying).
There are two solutions to the duplicate message processing problem:
- Either add duplicate message detection to your listener, in the form of a business entity existence check or a protocol table check. This usually just needs to be done in case of the JMSRedelivered flag being set on the incoming message (otherwise just process straightforwardly). Note that with "sessionTransacted" set to "true", duplicate messages will only appear in case of the JVM dying at the most unfortunate point possible (i.e. after your business logic executed but before the JMS part got committed), so duplicate message detection is just there to cover a corner case.
- Or wrap your entire processing with an XA transaction, covering the
reception of the JMS message as well as the execution of the business logic in
your message listener (including database operations etc). This is only
supported by
DefaultMessageListenerContainer
, through specifying an external "transactionManager" (typically aJtaTransactionManager
, with a corresponding XA-aware JMSConnectionFactory
passed in as "connectionFactory").
Recommendations:
- The general recommendation is to set "sessionTransacted" to "true", typically in combination with local database transactions triggered by the listener implementation, through Spring's standard transaction facilities. This will work nicely in Tomcat or in a standalone environment, often combined with custom duplicate message detection (if it is unacceptable to ever process the same message twice).
- Alternatively, specify a
JtaTransactionManager
as "transactionManager" for a fully XA-aware JMS provider - typically when running on a Jakarta EE server, but also for other environments with a JTA transaction manager present. This will give full "exactly-once" guarantees without custom duplicate message checks, at the price of additional runtime processing overhead.
Note that the "sessionTransacted" flag is strongly recommended over
JmsTransactionManager
, provided
that transactions do not need to be managed externally. As a consequence,
set the transaction manager only if you are using JTA or if you need to
synchronize with custom external transaction arrangements.
- Since:
- 2.0
- Author:
- Juergen Hoeller, Stephane Nicoll, Brian Clozel
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.springframework.jms.listener.AbstractJmsListeningContainer
AbstractJmsListeningContainer.SharedConnectionNotInitializedException
-
Field Summary
Fields inherited from class org.springframework.jms.listener.AbstractJmsListeningContainer
lifecycleMonitor, sharedConnectionMonitor
Fields inherited from class org.springframework.jms.support.destination.JmsDestinationAccessor
RECEIVE_TIMEOUT_INDEFINITE_WAIT, RECEIVE_TIMEOUT_NO_WAIT
Fields inherited from class org.springframework.jms.support.JmsAccessor
logger
Fields inherited from interface org.springframework.context.SmartLifecycle
DEFAULT_PHASE
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected void
checkMessageListener
(Object messageListener) Check the given message listener, throwing an exception if it does not correspond to a supported listener type.protected void
commitIfNecessary
(Session session, Message message) Perform a commit or message acknowledgement, as appropriate.protected MessageConsumer
createConsumer
(Session session, Destination destination) Create a JMS MessageConsumer for the given Session and Destination.protected io.micrometer.observation.Observation
createObservation
(Message message) protected void
doExecuteListener
(Session session, Message message) Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).protected void
doInvokeListener
(MessageListener listener, Message message) Invoke the specified listener as standard JMSMessageListener
.protected 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.protected void
executeListener
(Session session, Message message) Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).protected String
getDefaultSubscriptionName
(Object messageListener) Determine the default subscription name for the given message listener.Return the destination to receive messages from.protected String
Return a descriptive String for this container's JMS destination (nevernull
).Return the name of the destination to receive messages from.Return the name of a durable subscription to create, if any.Return theErrorHandler
to be invoked in case of any uncaught exceptions thrown while processing aMessage
.Return the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure, if any.Return theMessageConverter
that can be used to convertMessage
, if any.Return the message listener object to register.Return the JMS message selector expression (ornull
if none).io.micrometer.observation.ObservationRegistry
Return theObservationRegistry
used for recordingJMS message processing observations
.Return theQosSettings
to use when sending a reply, ornull
if the broker's defaults should be used.Return the name of a subscription to create, if any.protected void
Handle the given exception that arose during listener execution.protected void
Invoke the registeredErrorHandler
if any.protected void
Invoke the registered JMS ExceptionListener, if any.protected void
invokeListener
(Session session, Message message) Invoke the specified listener: either as standard JMS MessageListener or (preferably) as Spring SessionAwareMessageListener.boolean
Return whether to accept received messages while the listener container in the process of stopping.boolean
Return whether to expose the listener JMSSession
to a registeredSessionAwareMessageListener
.boolean
Return whether to inhibit the delivery of messages published by its own connection.boolean
Return whether the Publish/Subscribe domain (Topics
) is used for replies.protected 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
Return whether to make the subscription durable.boolean
Return whether to make the subscription shared.protected void
rollbackIfNecessary
(Session session) Perform a rollback, if appropriate.protected 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.abstract void
setConcurrency
(String concurrency) Specify concurrency limits.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 theErrorHandler
to be invoked in case of any uncaught exceptions thrown while processing aMessage
.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 registeredSessionAwareMessageListener
as well as toJmsTemplate
calls.void
setMessageConverter
(MessageConverter messageConverter) Set theMessageConverter
strategy for converting JMS Messages.void
setMessageListener
(Object messageListener) Set the message listener implementation to register.void
setMessageSelector
(String messageSelector) Set the JMS message selector expression (ornull
if none).void
setObservationRegistry
(io.micrometer.observation.ObservationRegistry observationRegistry) Set theObservationRegistry
to be used for recordingJMS message processing observations
.void
setPubSubNoLocal
(boolean pubSubNoLocal) Set whether to inhibit the delivery of messages published by its own connection.void
setReplyPubSubDomain
(boolean replyPubSubDomain) Configure the reply destination type.void
setReplyQosSettings
(QosSettings replyQosSettings) Configure theQosSettings
to use when sending a reply.void
setSubscriptionDurable
(boolean subscriptionDurable) Set whether to make the subscription durable.void
setSubscriptionName
(String subscriptionName) Set the name of a subscription to create.void
setSubscriptionShared
(boolean subscriptionShared) Set whether to make the subscription shared.void
setupMessageListener
(Object messageListener) Set up the message listener to use.protected void
Validate the configuration of this container.Methods inherited from class org.springframework.jms.listener.AbstractJmsListeningContainer
afterPropertiesSet, createSharedConnection, destroy, doInitialize, doRescheduleTask, doShutdown, doStart, doStop, establishSharedConnection, getBeanName, getClientId, getPausedTaskCount, getPhase, getSharedConnection, initialize, isActive, isAutoStartup, isRunning, logRejectedTask, prepareSharedConnection, refreshSharedConnection, releaseSharedConnection, rescheduleTaskIfNecessary, resumePausedTasks, runningAllowed, setAutoStartup, setBeanName, setClientId, setPhase, sharedConnectionEnabled, shutdown, start, startSharedConnection, stop, stopSharedConnection
Methods inherited from class org.springframework.jms.support.destination.JmsDestinationAccessor
getDestinationResolver, isPubSubDomain, receiveFromConsumer, resolveDestinationName, setDestinationResolver, setPubSubDomain
Methods inherited from class org.springframework.jms.support.JmsAccessor
convertJmsAccessException, createConnection, createSession, getConnectionFactory, getSessionAcknowledgeMode, isClientAcknowledge, isSessionTransacted, obtainConnectionFactory, setConnectionFactory, setSessionAcknowledgeMode, setSessionAcknowledgeModeName, setSessionTransacted
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.springframework.jms.listener.MessageListenerContainer
getDestinationResolver, isPubSubDomain
Methods inherited from interface org.springframework.context.SmartLifecycle
getPhase, isAutoStartup, stop
-
Constructor Details
-
AbstractMessageListenerContainer
public AbstractMessageListenerContainer()
-
-
Method Details
-
setConcurrency
Specify concurrency limits. -
setDestination
Set the destination to receive messages from.Alternatively, specify a "destinationName", to be dynamically resolved via the
DestinationResolver
.Note: The destination may be replaced at runtime, with the listener container picking up the new destination immediately (works e.g. with DefaultMessageListenerContainer, as long as the cache level is less than CACHE_CONSUMER). However, this is considered advanced usage; use it with care!
- See Also:
-
getDestination
Return the destination to receive messages from. Will benull
if the configured destination is not an actualDestination
type; c.f.when the destination is a String
. -
setDestinationName
Set the name of the destination to receive messages from.The specified name will be dynamically resolved via the configured
destination resolver
.Alternatively, specify a JMS
Destination
object as "destination".Note: The destination may be replaced at runtime, with the listener container picking up the new destination immediately (works e.g. with DefaultMessageListenerContainer, as long as the cache level is less than CACHE_CONSUMER). However, this is considered advanced usage; use it with care!
- See Also:
-
getDestinationName
Return the name of the destination to receive messages from. Will benull
if the configured destination is not aString
type; c.f.when it is an actual Destination
. -
getDestinationDescription
Return a descriptive String for this container's JMS destination (nevernull
). -
setMessageSelector
Set the JMS message selector expression (ornull
if none). Default is none.See the JMS specification for a detailed definition of selector expressions.
Note: The message selector may be replaced at runtime, with the listener container picking up the new selector value immediately (works e.g. with DefaultMessageListenerContainer, as long as the cache level is less than CACHE_CONSUMER). However, this is considered advanced usage; use it with care!
-
getMessageSelector
Return the JMS message selector expression (ornull
if none). -
setMessageListener
Set the message listener implementation to register. This can be either a standard JMSMessageListener
object or a SpringSessionAwareMessageListener
object.Note: The message listener may be replaced at runtime, with the listener container picking up the new listener object immediately (works e.g. with DefaultMessageListenerContainer, as long as the cache level is less than CACHE_CONSUMER). However, this is considered advanced usage; use it with care!
- Throws:
IllegalArgumentException
- if the supplied listener is not aMessageListener
or aSessionAwareMessageListener
- See Also:
-
getMessageListener
Return the message listener object to register. -
checkMessageListener
Check the given message listener, throwing an exception if it does not correspond to a supported listener type.By default, only a standard JMS
MessageListener
object or a SpringSessionAwareMessageListener
object will be accepted.- Parameters:
messageListener
- the message listener object to check- Throws:
IllegalArgumentException
- if the supplied listener is not aMessageListener
or aSessionAwareMessageListener
- See Also:
-
getDefaultSubscriptionName
Determine the default subscription name for the given message listener.- Parameters:
messageListener
- the message listener object to check- Returns:
- the default subscription name
- See Also:
-
setSubscriptionDurable
public void setSubscriptionDurable(boolean subscriptionDurable) Set whether to make the subscription durable. The durable subscription name to be used can be specified through the "subscriptionName" property.Default is "false". Set this to "true" to register a durable subscription, typically in combination with a "subscriptionName" value (unless your message listener class name is good enough as subscription name).
Only makes sense when listening to a topic (pub-sub domain), therefore this method switches the "pubSubDomain" flag as well.
-
isSubscriptionDurable
public boolean isSubscriptionDurable()Return whether to make the subscription durable. -
setSubscriptionName
Set the name of a subscription to create. To be applied in case of a topic (pub-sub domain) with a shared or durable subscription.The subscription name needs to be unique within this client's JMS client id. Default is the class name of the specified message listener.
Note: Only 1 concurrent consumer (which is the default of this message listener container) is allowed for each subscription, except for a shared subscription (which requires JMS 2.0).
-
getSubscriptionName
Return the name of a subscription to create, if any.- Since:
- 4.1
-
setDurableSubscriptionName
Set the name of a durable subscription to create. This method switches to pub-sub domain mode and activates subscription durability as well.The durable subscription name needs to be unique within this client's JMS client id. Default is the class name of the specified message listener.
Note: Only 1 concurrent consumer (which is the default of this message listener container) is allowed for each durable subscription, except for a shared durable subscription (which requires JMS 2.0).
-
getDurableSubscriptionName
Return the name of a durable subscription to create, if any. -
setPubSubNoLocal
public void setPubSubNoLocal(boolean pubSubNoLocal) Set whether to inhibit the delivery of messages published by its own connection. Default is "false".- Since:
- 4.1
- See Also:
-
isPubSubNoLocal
public boolean isPubSubNoLocal()Return whether to inhibit the delivery of messages published by its own connection.- Since:
- 4.1
-
setReplyPubSubDomain
public void setReplyPubSubDomain(boolean replyPubSubDomain) Configure the reply destination type. By default, the configuredpubSubDomain
value is used (seeJmsDestinationAccessor.isPubSubDomain()
).This setting primarily indicates what type of destination to resolve if dynamic destinations are enabled.
-
isReplyPubSubDomain
public boolean isReplyPubSubDomain()Return whether the Publish/Subscribe domain (Topics
) is used for replies. Otherwise, the Point-to-Point domain (Queues
) is used.- Specified by:
isReplyPubSubDomain
in interfaceMessageListenerContainer
- Since:
- 4.2
-
setReplyQosSettings
Configure theQosSettings
to use when sending a reply. Can be set tonull
to indicate that the broker's defaults should be used.- Parameters:
replyQosSettings
- the QoS settings to use when sending a reply, ornull
to use the default value- Since:
- 5.0
-
getReplyQosSettings
Description copied from interface:MessageListenerContainer
Return theQosSettings
to use when sending a reply, ornull
if the broker's defaults should be used.- Specified by:
getReplyQosSettings
in interfaceMessageListenerContainer
-
setMessageConverter
Set theMessageConverter
strategy for converting JMS Messages.- Since:
- 4.1
-
getMessageConverter
Description copied from interface:MessageListenerContainer
Return theMessageConverter
that can be used to convertMessage
, if any.- Specified by:
getMessageConverter
in interfaceMessageListenerContainer
-
setExceptionListener
Set the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure. -
getExceptionListener
Return the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure, if any. -
setErrorHandler
Set theErrorHandler
to be invoked in case of any uncaught exceptions thrown while processing aMessage
.By default, there will be no ErrorHandler so that error-level logging is the only result.
-
getErrorHandler
Return theErrorHandler
to be invoked in case of any uncaught exceptions thrown while processing aMessage
.- Since:
- 4.1
-
setObservationRegistry
public void setObservationRegistry(@Nullable io.micrometer.observation.ObservationRegistry observationRegistry) Set theObservationRegistry
to be used for recordingJMS message processing observations
. Defaults to no-op observations if the registry is not set.- Since:
- 6.1
-
getObservationRegistry
Return theObservationRegistry
used for recordingJMS message processing observations
.- Since:
- 6.1
-
setExposeListenerSession
public void setExposeListenerSession(boolean exposeListenerSession) Set whether to expose the listener JMS Session to a registeredSessionAwareMessageListener
as well as toJmsTemplate
calls.Default is "true", reusing the listener's
Session
. Turn this off to expose a fresh JMS Session fetched from the same underlying JMSConnection
instead, which might be necessary on some JMS providers.Note that Sessions managed by an external transaction manager will always get exposed to
JmsTemplate
calls. So in terms of JmsTemplate exposure, this setting only affects locally transacted Sessions.- See Also:
-
isExposeListenerSession
public boolean isExposeListenerSession()Return whether to expose the listener JMSSession
to a registeredSessionAwareMessageListener
. -
setAcceptMessagesWhileStopping
public void setAcceptMessagesWhileStopping(boolean acceptMessagesWhileStopping) Set whether to accept received messages while the listener container in the process of stopping.Default is "false", rejecting such messages through aborting the receive attempt. Switch this flag on to fully process such messages even in the stopping phase, with the drawback that even newly sent messages might still get processed (if coming in before all receive timeouts have expired).
NOTE: Aborting receive attempts for such incoming messages might lead to the provider's retry count decreasing for the affected messages. If you have a high number of concurrent consumers, make sure that the number of retries is higher than the number of consumers, to be on the safe side for all potential stopping scenarios.
-
isAcceptMessagesWhileStopping
public boolean isAcceptMessagesWhileStopping()Return whether to accept received messages while the listener container in the process of stopping. -
validateConfiguration
protected void validateConfiguration()Description copied from class:AbstractJmsListeningContainer
Validate the configuration of this container.The default implementation is empty. To be overridden in subclasses.
- Overrides:
validateConfiguration
in classAbstractJmsListeningContainer
-
setupMessageListener
Description copied from interface:MessageListenerContainer
Set up the message listener to use. Throws anIllegalArgumentException
if that message listener type is not supported.- Specified by:
setupMessageListener
in interfaceMessageListenerContainer
-
executeListener
Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).- Parameters:
session
- the JMS Session to operate onmessage
- the received JMSMessage
- See Also:
-
createObservation
-
doExecuteListener
Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).- Parameters:
session
- the JMS Session to operate onmessage
- the received JMSMessage
- Throws:
JMSException
- if thrown by JMS API methods- See Also:
-
invokeListener
Invoke the specified listener: either as standard JMS MessageListener or (preferably) as Spring SessionAwareMessageListener.- Parameters:
session
- the JMS Session to operate onmessage
- the received JMSMessage
- Throws:
JMSException
- if thrown by JMS API methods- See Also:
-
doInvokeListener
protected void doInvokeListener(SessionAwareMessageListener listener, Session session, Message message) throws JMSException Invoke the specified listener as Spring SessionAwareMessageListener, exposing a new JMS Session (potentially with its own transaction) to the listener if demanded.- Parameters:
listener
- the Spring SessionAwareMessageListener to invokesession
- the JMS Session to operate onmessage
- the received JMSMessage
- Throws:
JMSException
- if thrown by JMS API methods- See Also:
-
doInvokeListener
Invoke the specified listener as standard JMSMessageListener
.Default implementation performs a plain invocation of the
onMessage
method.- Parameters:
listener
- the JMSMessageListener
to invokemessage
- the received JMSMessage
- Throws:
JMSException
- if thrown by JMS API methods- See Also:
-
commitIfNecessary
Perform a commit or message acknowledgement, as appropriate.- Parameters:
session
- the JMSSession
to commitmessage
- theMessage
to acknowledge- Throws:
JMSException
- in case of commit failure
-
rollbackIfNecessary
Perform a rollback, if appropriate.- Parameters:
session
- the JMS Session to rollback- Throws:
JMSException
- in case of a rollback error
-
rollbackOnExceptionIfNecessary
Perform a rollback, handling rollback exceptions properly.- Parameters:
session
- the JMS Session to rollbackex
- the thrown application exception or error- Throws:
JMSException
- in case of a rollback error
-
isSessionLocallyTransacted
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.Note: The Session's own transacted flag will already have been checked before. This method is about finding out whether the Session's transaction is local or externally coordinated.
- Parameters:
session
- the Session to check- Returns:
- whether the given Session is locally transacted
- See Also:
-
createConsumer
protected MessageConsumer createConsumer(Session session, Destination destination) throws JMSException 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 fordestination
- the JMS Destination to create a MessageConsumer for- Returns:
- the new JMS MessageConsumer
- Throws:
JMSException
- if thrown by JMS API methods
-
handleListenerException
Handle the given exception that arose during listener execution.The default implementation logs the exception at
WARN
level, not propagating it to the JMS provider — assuming that all handling of acknowledgement and/or transactions is done by this listener container. This can be overridden in subclasses.- Parameters:
ex
- the exception to handle
-
invokeExceptionListener
Invoke the registered JMS ExceptionListener, if any.- Parameters:
ex
- the exception that arose during JMS processing- See Also:
-
invokeErrorHandler
Invoke the registeredErrorHandler
if any. Log atWARN
level otherwise.- Parameters:
ex
- the uncaught error that arose during JMS processing- See Also:
-