java.lang.Object | ||||
↳ | org.springframework.jms.support.JmsAccessor | |||
↳ | org.springframework.jms.support.destination.JmsDestinationAccessor | |||
↳ | org.springframework.jms.listener.AbstractJmsListeningContainer | |||
↳ | org.springframework.jms.listener.AbstractMessageListenerContainer |
Known Direct Subclasses |
Known Indirect Subclasses |
Abstract base class for message listener containers. Can either host
a standard JMS javax.jms.MessageListener or a Spring-specific
SessionAwareMessageListener
.
Usually holds a single JMS Connection that all listeners are supposed to be registered on, which is the standard JMS way of managing listeners. Can alternatively also be used with a fresh Connection per listener, for J2EE-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 the error 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
any 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:
There are two solutions to the duplicate processing problem:
DefaultMessageListenerContainer
, through
specifying a "transactionManager" (typically a
JtaTransactionManager
, with
a corresponding XA-aware JMS javax.jms.ConnectionFactory passed in as
"connectionFactory").
Recommendations:
JtaTransactionManager
as
"transactionManager" for a fully XA-aware JMS provider - typically when
running on a J2EE 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 it is also possible to specify a
JmsTransactionManager
as external
"transactionManager", providing fully synchronized Spring transactions based
on local JMS transactions. The effect is similar to "sessionTransacted" set
to "true", the difference being that this external transaction management
will also affect independent JMS access code within the service layer
(e.g. based on JmsTemplate
or
TransactionAwareConnectionFactoryProxy
),
not just direct JMS Session usage in a SessionAwareMessageListener
.
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.jms.listener.AbstractJmsListeningContainer
| |||||||||||
From class
org.springframework.jms.support.JmsAccessor
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Return the destination to receive messages from.
| |||||||||||
Return the name of the destination to receive messages from.
| |||||||||||
Return the name of a durable subscription to create, if any.
| |||||||||||
Return the JMS ExceptionListener to notify in case of a JMSException thrown
by the registered message listener or the invocation infrastructure, if any.
| |||||||||||
Return the message listener object to register.
| |||||||||||
Return the JMS message selector expression (or
null if none). | |||||||||||
Return whether to accept received messages while the listener container
in the process of stopping.
| |||||||||||
Return whether to expose the listener JMS Session to a
registered
SessionAwareMessageListener . | |||||||||||
Return whether to make the subscription durable.
| |||||||||||
Set whether to accept received messages while the listener container
in the process of stopping.
| |||||||||||
Set the destination to receive messages from.
| |||||||||||
Set the name of the destination to receive messages from.
| |||||||||||
Set the name of a durable subscription to create.
| |||||||||||
Set an ErrorHandler to be invoked in case of any uncaught exceptions thrown
while processing a Message.
| |||||||||||
Set the JMS ExceptionListener to notify in case of a JMSException thrown
by the registered message listener or the invocation infrastructure.
| |||||||||||
Set whether to expose the listener JMS Session to a registered
SessionAwareMessageListener as well as to
JmsTemplate calls. | |||||||||||
Set the message listener implementation to register.
| |||||||||||
Set the JMS message selector expression (or
null if none). | |||||||||||
Set whether to make the subscription durable.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Check the given message listener, throwing an exception
if it does not correspond to a supported listener type.
| |||||||||||
Perform a commit or message acknowledgement, as appropriate.
| |||||||||||
Execute the specified listener,
committing or rolling back the transaction afterwards (if necessary).
| |||||||||||
Invoke the specified listener as Spring SessionAwareMessageListener,
exposing a new JMS Session (potentially with its own transaction)
to the listener if demanded.
| |||||||||||
Invoke the specified listener as standard JMS MessageListener.
| |||||||||||
Execute the specified listener,
committing or rolling back the transaction afterwards (if necessary).
| |||||||||||
Determine the default subscription name for the given message listener.
| |||||||||||
Return a descriptive String for this container's JMS destination
(never
null ). | |||||||||||
Handle the given exception that arose during listener execution.
| |||||||||||
Invoke the registered ErrorHandler, if any.
| |||||||||||
Invoke the registered JMS ExceptionListener, if any.
| |||||||||||
Invoke the specified listener: either as standard JMS MessageListener
or (preferably) as Spring SessionAwareMessageListener.
| |||||||||||
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.
| |||||||||||
Perform a rollback, if appropriate.
| |||||||||||
Perform a rollback, handling rollback exceptions properly.
| |||||||||||
Validate the configuration of this container.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.jms.listener.AbstractJmsListeningContainer
| |||||||||||
From class
org.springframework.jms.support.destination.JmsDestinationAccessor
| |||||||||||
From class
org.springframework.jms.support.JmsAccessor
| |||||||||||
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
|
Return the destination to receive messages from. Will be null
if the configured destination is not an actual Destination type;
c.f. when the destination is a String
.
Return the name of the destination to receive messages from.
Will be null
if the configured destination is not a
String
type; c.f. when
it is an actual Destination
.
Return the name of a durable subscription to create, if any.
Return the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure, if any.
Return whether to accept received messages while the listener container in the process of stopping.
Return whether to expose the listener JMS Session to a
registered SessionAwareMessageListener
.
Return whether to make the subscription durable.
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.
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!
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!
destinationName | the desired destination (can be null ) |
---|
Set the name of a durable subscription to create. To be applied in case of a topic (pub-sub domain) with subscription durability activated.
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.
Set an ErrorHandler to be invoked in case of any uncaught exceptions thrown while processing a Message. By default there will be no ErrorHandler so that error-level logging is the only result.
Set the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure.
Set whether to expose the listener JMS Session to a registered
SessionAwareMessageListener
as well as to
JmsTemplate
calls.
Default is "true", reusing the listener's Session. Turn this off to expose a fresh JMS Session fetched from the same underlying JMS Connection 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.
Set the message listener implementation to register.
This can be either a standard JMS MessageListener object
or a Spring SessionAwareMessageListener
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!
IllegalArgumentException | if the supplied listener is not a
MessageListener or a SessionAwareMessageListener |
---|
SessionAwareMessageListener
Set the JMS message selector expression (or null
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!
Set whether to make the subscription durable. The durable subscription name to be used can be specified through the "durableSubscriptionName" property.
Default is "false". Set this to "true" to register a durable subscription, typically in combination with a "durableSubscriptionName" value (unless your message listener class name is good enough as subscription name).
Only makes sense when listening to a topic (pub-sub domain).
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
Spring SessionAwareMessageListener
object will be accepted.
messageListener | the message listener object to check |
---|
IllegalArgumentException | if the supplied listener is not a
MessageListener or a SessionAwareMessageListener |
---|
SessionAwareMessageListener
Perform a commit or message acknowledgement, as appropriate.
session | the JMS Session to commit |
---|---|
message | the Message to acknowledge |
in case of commit failure | |
JMSException |
Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).
session | the JMS Session to operate on |
---|---|
message | the received JMS Message |
if thrown by JMS API methods | |
JMSException |
Invoke the specified listener as Spring SessionAwareMessageListener, exposing a new JMS Session (potentially with its own transaction) to the listener if demanded.
listener | the Spring SessionAwareMessageListener to invoke |
---|---|
session | the JMS Session to operate on |
message | the received JMS Message |
if thrown by JMS API methods | |
JMSException |
Invoke the specified listener as standard JMS MessageListener.
Default implementation performs a plain invocation of the
onMessage
method.
listener | the JMS MessageListener to invoke |
---|---|
message | the received JMS Message |
if thrown by JMS API methods | |
JMSException |
Execute the specified listener, committing or rolling back the transaction afterwards (if necessary).
session | the JMS Session to operate on |
---|---|
message | the received JMS Message |
Determine the default subscription name for the given message listener.
messageListener | the message listener object to check |
---|
Return a descriptive String for this container's JMS destination
(never null
).
Handle the given exception that arose during listener execution.
The default implementation logs the exception at error 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.
ex | the exception to handle |
---|
Invoke the registered ErrorHandler, if any. Log at error level otherwise.
ex | the uncaught error that arose during JMS processing. |
---|
Invoke the registered JMS ExceptionListener, if any.
ex | the exception that arose during JMS processing |
---|
Invoke the specified listener: either as standard JMS MessageListener or (preferably) as Spring SessionAwareMessageListener.
session | the JMS Session to operate on |
---|---|
message | the received JMS Message |
if thrown by JMS API methods | |
JMSException |
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.
session | the Session to check |
---|
Perform a rollback, if appropriate.
session | the JMS Session to rollback |
---|
in case of a rollback error | |
JMSException |
Perform a rollback, handling rollback exceptions properly.
session | the JMS Session to rollback |
---|---|
ex | the thrown application exception or error |
in case of a rollback error | |
JMSException |
Validate the configuration of this container.
The default implementation is empty. To be overridden in subclasses.