|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.springframework.jms.support.JmsAccessor
org.springframework.jms.support.destination.JmsDestinationAccessor
org.springframework.jms.listener.AbstractJmsListeningContainer
org.springframework.jms.listener.AbstractMessageListenerContainer
public abstract class AbstractMessageListenerContainer
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
.
setMessageListener(java.lang.Object)
,
javax.jms.MessageListener
,
SessionAwareMessageListener
,
handleListenerException(java.lang.Throwable)
,
DefaultMessageListenerContainer
,
SimpleMessageListenerContainer
,
JmsMessageEndpointManager
Nested Class Summary | |
---|---|
private static class |
AbstractMessageListenerContainer.MessageRejectedWhileStoppingException
Internal exception class that indicates a rejected message on shutdown. |
Nested classes/interfaces inherited from class org.springframework.jms.listener.AbstractJmsListeningContainer |
---|
AbstractJmsListeningContainer.SharedConnectionNotInitializedException |
Field Summary | |
---|---|
private boolean |
acceptMessagesWhileStopping
|
private java.lang.Object |
destination
|
private java.lang.String |
durableSubscriptionName
|
private ErrorHandler |
errorHandler
|
private ExceptionListener |
exceptionListener
|
private boolean |
exposeListenerSession
|
private java.lang.Object |
messageListener
|
private java.lang.String |
messageSelector
|
private boolean |
subscriptionDurable
|
Fields inherited from class org.springframework.jms.listener.AbstractJmsListeningContainer |
---|
lifecycleMonitor, sharedConnectionMonitor |
Fields inherited from class org.springframework.jms.support.JmsAccessor |
---|
logger |
Constructor Summary | |
---|---|
AbstractMessageListenerContainer()
|
Method Summary | |
---|---|
protected void |
checkMessageListener(java.lang.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 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 JMS MessageListener. |
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 java.lang.String |
getDefaultSubscriptionName(java.lang.Object messageListener)
Determine the default subscription name for the given message listener. |
Destination |
getDestination()
Return the destination to receive messages from. |
protected java.lang.String |
getDestinationDescription()
Return a descriptive String for this container's JMS destination (never null ). |
java.lang.String |
getDestinationName()
Return the name of the destination to receive messages from. |
java.lang.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. |
java.lang.Object |
getMessageListener()
Return the message listener object to register. |
java.lang.String |
getMessageSelector()
Return the JMS message selector expression (or null if none). |
protected void |
handleListenerException(java.lang.Throwable ex)
Handle the given exception that arose during listener execution. |
protected void |
invokeErrorHandler(java.lang.Throwable ex)
Invoke the registered ErrorHandler, if any. |
protected void |
invokeExceptionListener(JMSException ex)
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 |
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 . |
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 |
isSubscriptionDurable()
Return whether to make the subscription durable. |
protected void |
rollbackIfNecessary(Session session)
Perform a rollback, if appropriate. |
protected void |
rollbackOnExceptionIfNecessary(Session session,
java.lang.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(java.lang.String destinationName)
Set the name of the destination to receive messages from. |
void |
setDurableSubscriptionName(java.lang.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(java.lang.Object messageListener)
Set the message listener implementation to register. |
void |
setMessageSelector(java.lang.String messageSelector)
Set the JMS message selector expression (or null if none). |
void |
setSubscriptionDurable(boolean subscriptionDurable)
Set whether to make the subscription durable. |
protected void |
validateConfiguration()
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, rescheduleTaskIfNecessary, resumePausedTasks, runningAllowed, setAutoStartup, setBeanName, setClientId, setPhase, sharedConnectionEnabled, shutdown, start, startSharedConnection, stop, stop, stopSharedConnection |
Methods inherited from class org.springframework.jms.support.destination.JmsDestinationAccessor |
---|
getDestinationResolver, isPubSubDomain, resolveDestinationName, setDestinationResolver, setPubSubDomain |
Methods inherited from class org.springframework.jms.support.JmsAccessor |
---|
convertJmsAccessException, createConnection, createSession, getConnectionFactory, getSessionAcknowledgeMode, isClientAcknowledge, isSessionTransacted, setConnectionFactory, setSessionAcknowledgeMode, setSessionAcknowledgeModeName, setSessionTransacted |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
private volatile java.lang.Object destination
private volatile java.lang.String messageSelector
private volatile java.lang.Object messageListener
private boolean subscriptionDurable
private java.lang.String durableSubscriptionName
private ExceptionListener exceptionListener
private ErrorHandler errorHandler
private boolean exposeListenerSession
private boolean acceptMessagesWhileStopping
Constructor Detail |
---|
public AbstractMessageListenerContainer()
Method Detail |
---|
public void setDestination(Destination destination)
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!
setDestinationName(String)
public Destination getDestination()
null
if the configured destination is not an actual Destination
type;
c.f. when the destination is a String
.
public void setDestinationName(java.lang.String destinationName)
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
)#setDestination(javax.jms.Destination)
public java.lang.String getDestinationName()
null
if the configured destination is not a
String
type; c.f. when
it is an actual Destination
.
protected java.lang.String getDestinationDescription()
null
).
public void setMessageSelector(java.lang.String messageSelector)
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!
public java.lang.String getMessageSelector()
null
if none).
public void setMessageListener(java.lang.Object messageListener)
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!
java.lang.IllegalArgumentException
- if the supplied listener is not a
MessageListener
or a SessionAwareMessageListener
javax.jms.MessageListener
,
SessionAwareMessageListener
public java.lang.Object getMessageListener()
protected void checkMessageListener(java.lang.Object messageListener)
By default, only a standard JMS MessageListener
object or a
Spring SessionAwareMessageListener
object will be accepted.
messageListener
- the message listener object to check
java.lang.IllegalArgumentException
- if the supplied listener is not a
MessageListener
or a SessionAwareMessageListener
javax.jms.MessageListener
,
SessionAwareMessageListener
protected java.lang.String getDefaultSubscriptionName(java.lang.Object messageListener)
messageListener
- the message listener object to check
SubscriptionNameProvider
public void setSubscriptionDurable(boolean subscriptionDurable)
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).
setDurableSubscriptionName(java.lang.String)
public boolean isSubscriptionDurable()
public void setDurableSubscriptionName(java.lang.String durableSubscriptionName)
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.
setSubscriptionDurable(boolean)
,
AbstractJmsListeningContainer.setClientId(java.lang.String)
,
setMessageListener(java.lang.Object)
public java.lang.String getDurableSubscriptionName()
public void setExceptionListener(ExceptionListener exceptionListener)
public ExceptionListener getExceptionListener()
public void setErrorHandler(ErrorHandler errorHandler)
public void setExposeListenerSession(boolean exposeListenerSession)
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.
SessionAwareMessageListener
public boolean isExposeListenerSession()
Session
to a
registered SessionAwareMessageListener
.
public void setAcceptMessagesWhileStopping(boolean acceptMessagesWhileStopping)
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.
public boolean isAcceptMessagesWhileStopping()
protected void validateConfiguration()
AbstractJmsListeningContainer
The default implementation is empty. To be overridden in subclasses.
validateConfiguration
in class AbstractJmsListeningContainer
protected void executeListener(Session session, Message message)
session
- the JMS Session to operate onmessage
- the received JMS MessageinvokeListener(Session, Message)
,
commitIfNecessary(Session, Message)
,
rollbackOnExceptionIfNecessary(Session, java.lang.Throwable)
,
handleListenerException(java.lang.Throwable)
protected void doExecuteListener(Session session, Message message) throws JMSException
session
- the JMS Session to operate onmessage
- the received JMS Message
JMSException
- if thrown by JMS API methodsinvokeListener(Session, Message)
,
commitIfNecessary(Session, Message)
,
rollbackOnExceptionIfNecessary(Session, java.lang.Throwable)
,
JmsAccessor.convertJmsAccessException(JMSException)
protected void invokeListener(Session session, Message message) throws JMSException
session
- the JMS Session to operate onmessage
- the received JMS Message
JMSException
- if thrown by JMS API methodssetMessageListener(java.lang.Object)
protected void doInvokeListener(SessionAwareMessageListener listener, Session session, Message message) throws JMSException
listener
- the Spring SessionAwareMessageListener to invokesession
- the JMS Session to operate onmessage
- the received JMS Message
JMSException
- if thrown by JMS API methodsSessionAwareMessageListener
,
setExposeListenerSession(boolean)
protected void doInvokeListener(MessageListener listener, Message message) throws JMSException
Default implementation performs a plain invocation of the
onMessage
method.
listener
- the JMS MessageListener to invokemessage
- the received JMS Message
JMSException
- if thrown by JMS API methodsjavax.jms.MessageListener#onMessage
protected void commitIfNecessary(Session session, Message message) throws JMSException
session
- the JMS Session to commitmessage
- the Message to acknowledge
javax.jms.JMSException
- in case of commit failure
JMSException
protected void rollbackIfNecessary(Session session) throws JMSException
session
- the JMS Session to rollback
javax.jms.JMSException
- in case of a rollback error
JMSException
protected void rollbackOnExceptionIfNecessary(Session session, java.lang.Throwable ex) throws JMSException
session
- the JMS Session to rollbackex
- the thrown application exception or error
javax.jms.JMSException
- in case of a rollback error
JMSException
protected boolean isSessionLocallyTransacted(Session session)
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
JmsAccessor.isSessionTransacted()
,
ConnectionFactoryUtils.isSessionTransactional(Session, ConnectionFactory)
protected void handleListenerException(java.lang.Throwable ex)
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.
ex
- the exception to handleprotected void invokeExceptionListener(JMSException ex)
ex
- the exception that arose during JMS processingsetExceptionListener(ExceptionListener)
protected void invokeErrorHandler(java.lang.Throwable ex)
ex
- the uncaught error that arose during JMS processing.setErrorHandler(org.springframework.util.ErrorHandler)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |