public abstract class

AbstractJmsListeningContainer

extends JmsDestinationAccessor
implements BeanNameAware DisposableBean SmartLifecycle
java.lang.Object
   ↳ org.springframework.jms.support.JmsAccessor
     ↳ org.springframework.jms.support.destination.JmsDestinationAccessor
       ↳ org.springframework.jms.listener.AbstractJmsListeningContainer
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Common base class for all containers which need to implement listening based on a JMS Connection (either shared or freshly obtained for each attempt). Inherits basic Connection and Session configuration handling from the JmsAccessor base class.

This class provides basic lifecycle management, in particular management of a shared JMS Connection. Subclasses are supposed to plug into this lifecycle, implementing the sharedConnectionEnabled() as well as the doInitialize() and doShutdown() template methods.

This base class does not assume any specific listener programming model or listener invoker mechanism. It just provides the general runtime lifecycle management needed for any kind of JMS-based listening mechanism that operates on a JMS Connection/Session.

For a concrete listener programming model, check out the AbstractMessageListenerContainer subclass. For a concrete listener invoker mechanism, check out the DefaultMessageListenerContainer class.

See Also

Summary

Nested Classes
class AbstractJmsListeningContainer.SharedConnectionNotInitializedException Exception that indicates that the initial setup of this container's shared JMS Connection failed. 
Fields
protected final Object lifecycleMonitor
protected final Object sharedConnectionMonitor
[Expand]
Inherited Fields
From class org.springframework.jms.support.JmsAccessor
Public Constructors
AbstractJmsListeningContainer()
Public Methods
void afterPropertiesSet()
Delegates to validateConfiguration() and initialize().
void destroy()
Calls shutdown() when the BeanFactory destroys the container instance.
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.
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 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.
void shutdown()
Stop the shared Connection, call doShutdown(), and close this container.
void start()
Start this container.
void stop()
Stop this container.
void stop(Runnable callback)
Indicates that a Lifecycle component must stop if it is currently running.
Protected Methods
Connection createSharedConnection()
Create a shared Connection for this container.
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.
final Connection getSharedConnection()
Return the shared JMS Connection maintained by this container.
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.
abstract boolean sharedConnectionEnabled()
Return whether a shared JMS Connection should be maintained by this container base class.
void startSharedConnection()
Start the shared Connection.
void stopSharedConnection()
Stop the shared Connection.
void validateConfiguration()
Validate the configuration of this container.
[Expand]
Inherited Methods
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

Fields

protected final Object lifecycleMonitor

protected final Object sharedConnectionMonitor

Public Constructors

public AbstractJmsListeningContainer ()

Public Methods

public void afterPropertiesSet ()

Delegates to validateConfiguration() and initialize().

public void destroy ()

Calls shutdown() when the BeanFactory destroys the container instance.

See Also

public String getClientId ()

Return the JMS client ID for the shared Connection created and used by this container, if any.

public int getPausedTaskCount ()

Determine the number of currently paused tasks, if any.

public int getPhase ()

Return the phase in which this container will be started and stopped.

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().

Throws
JmsException if startup failed

public final boolean isActive ()

Return whether this container is currently active, that is, whether it has been set up but not shut down yet.

public boolean isAutoStartup ()

Return whether this Lifecycle component should be started automatically by the container when the ApplicationContext is refreshed. A value of "false" indicates that the component is intended to be started manually.

public final boolean isRunning ()

Determine whether this container is currently running, that is, whether it has been started and not stopped yet.

Returns
  • whether the component is currently running
See Also

public void setAutoStartup (boolean autoStartup)

Set whether to automatically start the container after initialization.

Default is "true"; set this to "false" to allow for manual startup through the start() method.

public void setBeanName (String beanName)

Set the name of the bean in the bean factory that created this bean.

Invoked after population of normal bean properties but before an init callback such as afterPropertiesSet() or a custom init-method.

Parameters
beanName the name of the bean in the factory. Note that this name is the actual bean name used in the factory, which may differ from the originally specified name: in particular for inner bean names, the actual bean name might have been made unique through appending "#..." suffixes. Use the BeanFactoryUtils#originalBeanName(String) method to extract the original bean name (without suffix), if desired.

public void setClientId (String clientId)

Specify the JMS client id for a shared Connection created and used by this container.

Note that client ids need to be unique among all active Connections of the underlying JMS provider. Furthermore, a client id can only be assigned if the original ConnectionFactory hasn't already assigned one.

See Also

public void setPhase (int phase)

Specify the phase in which this container should be started and stopped. The startup order proceeds from lowest to highest, and the shutdown order is the reverse of that. By default this value is Integer.MAX_VALUE meaning that this container starts as late as possible and stops as soon as possible.

public void shutdown ()

Stop the shared Connection, call doShutdown(), and close this container.

Throws
JmsException if shutdown failed

public void start ()

Start this container.

Throws
JmsException if starting failed
See Also

public void stop ()

Stop this container.

Throws
JmsException if stopping failed
See Also

public void stop (Runnable callback)

Indicates that a Lifecycle component must stop if it is currently running.

The provided callback is used by the LifecycleProcessor to support an ordered, and potentially concurrent, shutdown of all components having a common shutdown order value. The callback must be executed after the SmartLifecycle component does indeed stop.

Protected Methods

protected Connection createSharedConnection ()

Create a shared Connection for this container.

The default implementation creates a standard Connection and prepares it through prepareSharedConnection(Connection).

Returns
  • the prepared Connection
Throws
if the creation failed
JMSException

protected abstract void doInitialize ()

Register any invokers within this container.

Subclasses need to implement this method for their specific invoker management process.

A shared JMS Connection, if any, will already have been started at this point.

Throws
if registration failed
JMSException
See Also

protected void doRescheduleTask (Object task)

Reschedule the given task object immediately.

To be implemented by subclasses if they ever call rescheduleTaskIfNecessary. This implementation throws an UnsupportedOperationException.

Parameters
task the task object to reschedule
See Also

protected abstract void doShutdown ()

Close the registered invokers.

Subclasses need to implement this method for their specific invoker management process.

A shared JMS Connection, if any, will automatically be closed afterwards.

Throws
if shutdown failed
JMSException
See Also

protected void doStart ()

Start the shared Connection, if any, and notify all invoker tasks.

Throws
if thrown by JMS API methods
JMSException
See Also

protected void doStop ()

Notify all invoker tasks and stop the shared Connection, if any.

Throws
if thrown by JMS API methods
JMSException
See Also

protected void establishSharedConnection ()

Establish a shared Connection for this container.

The default implementation delegates to createSharedConnection(), which does one immediate attempt and throws an exception if it fails. Can be overridden to have a recovery process in place, retrying until a Connection can be successfully established.

Throws
if thrown by JMS API methods
JMSException

protected final String getBeanName ()

Return the bean name that this listener container has been assigned in its containing bean factory, if any.

protected final Connection getSharedConnection ()

Return the shared JMS Connection maintained by this container. Available after initialization.

Returns
  • the shared Connection (never null)
Throws
IllegalStateException if this container does not maintain a shared Connection, or if the Connection hasn't been initialized yet
See Also

protected void logRejectedTask (Object task, RuntimeException ex)

Log a task that has been rejected by doRescheduleTask(Object).

The default implementation simply logs a corresponding message at debug level.

Parameters
task the rejected task object
ex the exception thrown from doRescheduleTask(Object)

protected void prepareSharedConnection (Connection connection)

Prepare the given Connection, which is about to be registered as shared Connection for this container.

The default implementation sets the specified client id, if any. Subclasses can override this to apply further settings.

Parameters
connection the Connection to prepare
Throws
if the preparation efforts failed
JMSException
See Also

protected final void refreshSharedConnection ()

Refresh the shared Connection that this container holds.

Called on startup and also after an infrastructure exception that occurred during invoker setup and/or execution.

Throws
if thrown by JMS API methods
JMSException

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

If this container has already been shut down, the task will not get rescheduled at all.

Parameters
task the task object to reschedule
Returns
  • whether the task has been rescheduled (either immediately or for a restart of this container)
See Also

protected void resumePausedTasks ()

Try to resume all paused tasks. Tasks for which rescheduling failed simply remain in paused mode.

protected boolean runningAllowed ()

Check whether this container's listeners are generally allowed to run.

This implementation always returns true; the default 'running' state is purely determined by start() / stop().

Subclasses may override this method to check against temporary conditions that prevent listeners from actually running. In other words, they may apply further restrictions to the 'running' state, returning false if such a restriction prevents listeners from running.

protected abstract boolean sharedConnectionEnabled ()

Return whether a shared JMS Connection should be maintained by this container base class.

See Also

protected void startSharedConnection ()

Start the shared Connection.

Throws
if thrown by JMS API methods
JMSException
See Also
  • javax.jms.Connection#start()

protected void stopSharedConnection ()

Stop the shared Connection.

Throws
if thrown by JMS API methods
JMSException
See Also
  • javax.jms.Connection#start()

protected void validateConfiguration ()

Validate the configuration of this container.

The default implementation is empty. To be overridden in subclasses.