|
The Spring Framework | |||||||||
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 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.
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 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)
,
MessageListener
,
SessionAwareMessageListener
,
handleListenerException(java.lang.Throwable)
,
DefaultMessageListenerContainer
,
SimpleMessageListenerContainer
,
ServerSessionMessageListenerContainer
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.JmsAccessor |
---|
logger |
Constructor Summary | |
---|---|
AbstractMessageListenerContainer()
|
Method Summary | |
---|---|
protected 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 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). |
Destination |
getDestination()
Return the destination to receive messages from. |
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). |
protected void |
handleListenerException(Throwable ex)
Handle the given exception that arose during listener execution. |
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,
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 |
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 . |
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. |
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, getSharedConnection, initialize, isActive, isRunning, prepareSharedConnection, refreshSharedConnection, rescheduleTaskIfNecessary, setAutoStartup, setBeanName, setClientId, sharedConnectionEnabled, shutdown, start, startSharedConnection, stop, stopSharedConnection, waitWhileNotRunning |
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 |
Constructor Detail |
---|
public AbstractMessageListenerContainer()
Method Detail |
---|
public void setDestination(Destination destination)
Alternatively, specify a "destinationName", to be dynamically
resolved via the DestinationResolver
.
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(String destinationName)
The specified name will be dynamically resolved via the configured
destination resolver
.
Alternatively, specify a JMS Destination
object as "destination".
destinationName
- the desired destination (can be null
)setDestination(javax.jms.Destination)
public String getDestinationName()
null
if the configured destination is not a
String
type; c.f. when
it is an actual Destination
.
public void setMessageSelector(String messageSelector)
null
if none).
Default is none.
See the JMS specification for a detailed definition of selector expressions.
public String getMessageSelector()
null
if none).
public void setMessageListener(Object messageListener)
MessageListener
object
or a Spring SessionAwareMessageListener
object.
IllegalArgumentException
- if the supplied listener is not a
MessageListener
or a SessionAwareMessageListener
MessageListener
,
SessionAwareMessageListener
protected void checkMessageListener(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
IllegalArgumentException
- if the supplied listener is not a
MessageListener
or a SessionAwareMessageListener
MessageListener
,
SessionAwareMessageListener
public Object getMessageListener()
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(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 String getDurableSubscriptionName()
public void setExceptionListener(ExceptionListener exceptionListener)
public ExceptionListener getExceptionListener()
public void setExposeListenerSession(boolean exposeListenerSession)
SessionAwareMessageListener
. 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.
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(javax.jms.Session, javax.jms.Message)
,
commitIfNecessary(javax.jms.Session, javax.jms.Message)
,
rollbackOnExceptionIfNecessary(javax.jms.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(javax.jms.Session, javax.jms.Message)
,
commitIfNecessary(javax.jms.Session, javax.jms.Message)
,
rollbackOnExceptionIfNecessary(javax.jms.Session, java.lang.Throwable)
,
JmsAccessor.convertJmsAccessException(javax.jms.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 methodsMessageListener.onMessage(javax.jms.Message)
protected void commitIfNecessary(Session session, Message message) throws JMSException
session
- the JMS Session to commitmessage
- the Message to acknowledge
JMSException
- in case of commit failureprotected void rollbackIfNecessary(Session session) throws JMSException
session
- the JMS Session to rollback
JMSException
- in case of a rollback errorprotected void rollbackOnExceptionIfNecessary(Session session, Throwable ex) throws JMSException
session
- the JMS Session to rollbackex
- the thrown application exception or error
JMSException
- in case of a rollback errorprotected 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(javax.jms.Session, javax.jms.ConnectionFactory)
protected void handleListenerException(Throwable ex)
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 handleprotected void invokeExceptionListener(JMSException ex)
ex
- the exception that arose during JMS processingsetExceptionListener(javax.jms.ExceptionListener)
|
The Spring Framework | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |