public abstract class

AbstractPollingMessageListenerContainer

extends AbstractMessageListenerContainer
implements BeanNameAware

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.AbstractPollingMessageListenerContainer

Known Direct Subclasses

DefaultMessageListenerContainer

Known Indirect Subclasses

DefaultMessageListenerContainer102

Class Overview

Base class for listener container implementations which are based on polling. Provides support for listener handling based on javax.jms.MessageConsumer, optionally participating in externally managed transactions.

This listener container variant is built for repeated polling attempts, each invoking the receiveAndExecute(Object, Session, MessageConsumer) method. The MessageConsumer used may be reobtained fo reach attempt or cached inbetween attempts; this is up to the concrete implementation. The receive timeout for each attempt can be configured through the "receiveTimeout" property.

The underlying mechanism is based on standard JMS MessageConsumer handling, which is perfectly compatible with both native JMS and JMS in a J2EE environment. Neither the JMS MessageConsumer.setMessageListener facility nor the JMS ServerSessionPool facility is required. A further advantage of this approach is full control over the listening process, allowing for custom scaling and throttling and of concurrent message processing (which is up to concrete subclasses).

Message reception and listener execution can automatically be wrapped in transactions through passing a Spring PlatformTransactionManager into the "transactionManager" property. This will usually be a JtaTransactionManager in a J2EE enviroment, in combination with a JTA-aware JMS ConnectionFactory obtained from JNDI (check your J2EE server's documentation).

This base class does not assume any specific mechanism for asynchronous execution of polling invokers. Check out DefaultMessageListenerContainer for a concrete implementation which is based on Spring's TaskExecutor abstraction, including dynamic scaling of concurrent consumers and automatic self recovery.

Summary

Constants
long	DEFAULT_RECEIVE_TIMEOUT	The default receive timeout: 1000 ms = 1 second.

[Expand]

Inherited Fields

From class org.springframework.jms.listener.AbstractJmsListeningContainer

From class org.springframework.jms.support.JmsAccessor

Public Constructors
	AbstractPollingMessageListenerContainer()

Public Methods
void	initialize() Initialize this container.
void	setPubSubNoLocal(boolean pubSubNoLocal) Set whether to inhibit the delivery of messages published by its own connection.
void	setReceiveTimeout(long receiveTimeout) Set the timeout to use for receive calls, in milliseconds.
void	setSessionTransacted(boolean sessionTransacted) Set the transaction mode that is used when creating a JMS Session.
void	setTransactionManager(PlatformTransactionManager transactionManager) Specify the Spring `PlatformTransactionManager` to use for transactional wrapping of message reception plus listener execution.
void	setTransactionName(String transactionName) Specify the transaction name to use for transactional wrapping.
void	setTransactionTimeout(int transactionTimeout) Specify the transaction timeout to use for transactional wrapping, in seconds.

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.
boolean	doReceiveAndExecute(Object invoker, Session session, MessageConsumer consumer, TransactionStatus status) Actually execute the listener for a message received from the given consumer, fetching all requires resources and invoking the listener.
Connection	getConnection(JmsResourceHolder holder) Fetch an appropriate Connection from the given JmsResourceHolder.
Session	getSession(JmsResourceHolder holder) Fetch an appropriate Session from the given JmsResourceHolder.
final PlatformTransactionManager	getTransactionManager() Return the Spring PlatformTransactionManager to use for transactional wrapping of message reception plus listener execution.
boolean	isPubSubNoLocal() Return whether to inhibit the delivery of messages published by its own connection.
boolean	isSessionLocallyTransacted(Session session) This implementation checks whether the Session is externally synchronized.
void	messageReceived(Object invoker, Session session) Template method that gets called right when a new message has been received, before attempting to process it.
void	noMessageReceived(Object invoker, Session session) Template method that gets called when no message has been received, before returning to the receive loop again.
boolean	receiveAndExecute(Object invoker, Session session, MessageConsumer consumer) Execute the listener for a message received from the given consumer, wrapping the entire operation in an external transaction if demanded.
Message	receiveMessage(MessageConsumer consumer) Receive a message from the given consumer.
boolean	shouldCommitAfterNoMessageReceived(Session session) Determine whether to trigger a commit after no message has been received.

[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

Constants

public static final long DEFAULT_RECEIVE_TIMEOUT

The default receive timeout: 1000 ms = 1 second.

Constant Value: 1000 (0x00000000000003e8)

Public Constructors

public AbstractPollingMessageListenerContainer ()

Public Methods

public void initialize ()

Initialize this container.

Creates a JMS Connection, starts the javax.jms.Connection (if "autoStartup" hasn't been turned off), and calls doInitialize().

public void setPubSubNoLocal (boolean pubSubNoLocal)

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

public void setReceiveTimeout (long receiveTimeout)

Set the timeout to use for receive calls, in milliseconds. The default is 1000 ms, that is, 1 second.

NOTE: This value needs to be smaller than the transaction timeout used by the transaction manager (in the appropriate unit, of course). -1 indicates no timeout at all; however, this is only feasible if not running within a transaction manager.

public void setSessionTransacted (boolean sessionTransacted)

Set the transaction mode that is used when creating a JMS Session. Default is "false".

Note that within a JTA transaction, the parameters passed to create(Queue/Topic)Session(boolean transacted, int acknowledgeMode) method are not taken into account. Depending on the J2EE transaction context, the container makes its own decisions on these values. Analogously, these parameters are not taken into account within a locally managed transaction either, since the accessor operates on an existing JMS Session in this case.

Setting this flag to "true" will use a short local JMS transaction when running outside of a managed transaction, and a synchronized local JMS transaction in case of a managed transaction (other than an XA transaction) being present. The latter has the effect of a local JMS transaction being managed alongside the main transaction (which might be a native JDBC transaction), with the JMS transaction committing right after the main transaction.

public void setTransactionManager (PlatformTransactionManager transactionManager)

Specify the Spring PlatformTransactionManager to use for transactional wrapping of message reception plus listener execution.

Default is none, not performing any transactional wrapping. If specified, this will usually be a Spring JtaTransactionManager or one of its subclasses, in combination with a JTA-aware ConnectionFactory that this message listener container obtains its Connections from.

Note: Consider the use of local JMS transactions instead. Simply switch the "sessionTransacted" flag to "true" in order to use a locally transacted JMS Session for the entire receive processing, including any Session operations performed by a SessionAwareMessageListener (e.g. sending a response message). Alternatively, a JmsTransactionManager may be used for fully synchronized Spring transactions based on local JMS transactions. Check AbstractMessageListenerContainer's javadoc for a discussion of transaction choices and message redelivery scenarios.

public void setTransactionName (String transactionName)

Specify the transaction name to use for transactional wrapping. Default is the bean name of this listener container, if any.

public void setTransactionTimeout (int transactionTimeout)

Specify the transaction timeout to use for transactional wrapping, in seconds. Default is none, using the transaction manager's default timeout.

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 boolean doReceiveAndExecute (Object invoker, Session session, MessageConsumer consumer, TransactionStatus status)

Actually execute the listener for a message received from the given consumer, fetching all requires resources and invoking the listener.

Parameters

session	the JMS Session to work on
consumer	the MessageConsumer to work on
status	the TransactionStatus (may be `null`)

Returns

whether a message has been received

Throws

	if thrown by JMS methods
JMSException

protected Connection getConnection (JmsResourceHolder holder)

Fetch an appropriate Connection from the given JmsResourceHolder.

This implementation accepts any JMS 1.1 Connection.

Parameters

holder	the JmsResourceHolder

Returns

an appropriate Connection fetched from the holder, or null if none found

protected Session getSession (JmsResourceHolder holder)

Fetch an appropriate Session from the given JmsResourceHolder.

This implementation accepts any JMS 1.1 Session.

Parameters

holder	the JmsResourceHolder

Returns

an appropriate Session fetched from the holder, or null if none found

protected final PlatformTransactionManager getTransactionManager ()

Return the Spring PlatformTransactionManager to use for transactional wrapping of message reception plus listener execution.

protected boolean isPubSubNoLocal ()

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

protected boolean isSessionLocallyTransacted (Session session)

This implementation checks whether the Session is externally synchronized. In this case, the Session is not locally transacted, despite the listener container's "sessionTransacted" flag being set to "true".

Parameters

session	the Session to check

Returns

whether the given Session is locally transacted

protected void messageReceived (Object invoker, Session session)

Template method that gets called right when a new message has been received, before attempting to process it. Allows subclasses to react to the event of an actual incoming message, for example adapting their consumer count.

Parameters

invoker	the invoker object (passed through)
session	the receiving JMS Session

protected void noMessageReceived (Object invoker, Session session)

Template method that gets called when no message has been received, before returning to the receive loop again. Allows subclasses to react to the event of no incoming message, for example marking the invoker as idle.

Parameters

invoker	the invoker object (passed through)
session	the receiving JMS Session

protected boolean receiveAndExecute (Object invoker, Session session, MessageConsumer consumer)

Execute the listener for a message received from the given consumer, wrapping the entire operation in an external transaction if demanded.

Parameters

session	the JMS Session to work on
consumer	the MessageConsumer to work on

Returns

whether a message has been received

Throws

	if thrown by JMS methods
JMSException

protected Message receiveMessage (MessageConsumer consumer)

Receive a message from the given consumer.

Parameters

consumer	the MessageConsumer to use

Returns

the Message, or null if none

Throws

	if thrown by JMS methods
JMSException

protected boolean shouldCommitAfterNoMessageReceived (Session session)

Determine whether to trigger a commit after no message has been received. This is a good idea on any JMS provider other than Tibco, which is what this default implementation checks for.

Parameters

session	the current JMS Session which received no message

Returns

whether to call commitIfNecessary(Session, Message) on the given Session

Interfaces

Classes

Exceptions

AbstractPollingMessageListenerContainer

Class Overview

See Also

Summary

Constants

public static final long DEFAULT_RECEIVE_TIMEOUT

Public Constructors

public AbstractPollingMessageListenerContainer ()

Public Methods

public void initialize ()

public void setPubSubNoLocal (boolean pubSubNoLocal)

See Also

public void setReceiveTimeout (long receiveTimeout)

See Also

public void setSessionTransacted (boolean sessionTransacted)

public void setTransactionManager (PlatformTransactionManager transactionManager)

See Also

public void setTransactionName (String transactionName)

See Also

public void setTransactionTimeout (int transactionTimeout)

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 boolean doReceiveAndExecute (Object invoker, Session session, MessageConsumer consumer, TransactionStatus status)

Parameters

Returns

Throws

See Also

protected Connection getConnection (JmsResourceHolder holder)

Parameters

Returns

protected Session getSession (JmsResourceHolder holder)

Parameters

Returns

protected final PlatformTransactionManager getTransactionManager ()

protected boolean isPubSubNoLocal ()

protected boolean isSessionLocallyTransacted (Session session)

Parameters

Returns

See Also

protected void messageReceived (Object invoker, Session session)

Parameters

protected void noMessageReceived (Object invoker, Session session)

Parameters

protected boolean receiveAndExecute (Object invoker, Session session, MessageConsumer consumer)

Parameters

Returns

Throws

See Also

protected Message receiveMessage (MessageConsumer consumer)

Parameters

Returns

Throws

protected boolean shouldCommitAfterNoMessageReceived (Session session)

Parameters

Returns