Package org.springframework.jms.listener

Class AbstractJmsListeningContainer

java.lang.Object
org.springframework.jms.support.JmsAccessor
org.springframework.jms.support.destination.JmsDestinationAccessor
org.springframework.jms.listener.AbstractJmsListeningContainer
All Implemented Interfaces:
Aware, BeanNameAware, DisposableBean, InitializingBean, Lifecycle, Phased, SmartLifecycle
Direct Known Subclasses:
AbstractMessageListenerContainer
public abstract class AbstractJmsListeningContainer extends JmsDestinationAccessor implements BeanNameAware, DisposableBean, SmartLifecycle
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.

Since:
2.0.3
Author:
Juergen Hoeller
See Also:

  • Field Details

    • sharedConnectionMonitor

      protected final Object sharedConnectionMonitor

    • lifecycleMonitor

      protected final Object lifecycleMonitor

  • Constructor Details

    • AbstractJmsListeningContainer

      public AbstractJmsListeningContainer()

  • Method Details

    • setClientId

      public void setClientId(@Nullable 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:

    • getClientId

      @Nullable public String getClientId()
      Return the JMS client ID for the shared Connection created and used by this container, if any.

    • setAutoStartup

      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.

    • isAutoStartup

      public boolean isAutoStartup()
      Description copied from interface: SmartLifecycle
      Returns true if this Lifecycle component should get started automatically by the container at the time that the containing ApplicationContext gets refreshed.

      A value of false indicates that the component is intended to be started through an explicit Lifecycle.start() call instead, analogous to a plain Lifecycle implementation.

      The default implementation returns true.

      Specified by:
      isAutoStartup in interface SmartLifecycle
      See Also:

    • setPhase

      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.

    • getPhase

      public int getPhase()
      Return the phase in which this container will be started and stopped.
      Specified by:
      getPhase in interface Phased
      Specified by:
      getPhase in interface SmartLifecycle
      See Also:

    • setBeanName

      public void setBeanName(@Nullable String beanName)
      Description copied from interface: BeanNameAware
      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 InitializingBean.afterPropertiesSet() or a custom init-method.

      Specified by:
      setBeanName in interface BeanNameAware
      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.

    • getBeanName

      @Nullable protected final String getBeanName()
      Return the bean name that this listener container has been assigned in its containing bean factory, if any.

    • afterPropertiesSet

      public void afterPropertiesSet()
      Delegates to validateConfiguration() and initialize().
      Specified by:
      afterPropertiesSet in interface InitializingBean
      Overrides:
      afterPropertiesSet in class JmsAccessor

    • validateConfiguration

      protected void validateConfiguration()
      Validate the configuration of this container.

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

    • destroy

      public void destroy()
      Calls shutdown() when the BeanFactory destroys the container instance.
      Specified by:
      destroy in interface DisposableBean
      See Also:

    • initialize

      public void initialize() throws JmsException
      Initialize this container.

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

      Throws:
      JmsException - if startup failed

    • shutdown

      public void shutdown() throws JmsException
      Stop the shared Connection, call doShutdown(), and close this container.
      Throws:
      JmsException - if shutdown failed

    • isActive

      public final boolean isActive()
      Return whether this container is currently active, that is, whether it has been set up but not shut down yet.

    • start

      public void start() throws JmsException
      Start this container.
      Specified by:
      start in interface Lifecycle
      Throws:
      JmsException - if starting failed
      See Also:

    • doStart

      protected void doStart() throws JMSException
      Start the shared Connection, if any, and notify all invoker tasks.
      Throws:
      JMSException - if thrown by JMS API methods
      See Also:

    • stop

      public void stop() throws JmsException
      Stop this container.
      Specified by:
      stop in interface Lifecycle
      Throws:
      JmsException - if stopping failed
      See Also:

    • doStop

      protected void doStop() throws JMSException
      Notify all invoker tasks and stop the shared Connection, if any.
      Throws:
      JMSException - if thrown by JMS API methods
      See Also:

    • isRunning

      public final boolean isRunning()
      Determine whether this container is currently running, that is, whether it has been started and not stopped yet.
      Specified by:
      isRunning in interface Lifecycle
      Returns:
      whether the component is currently running
      See Also:

    • runningAllowed

      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.

    • establishSharedConnection

      protected void establishSharedConnection() throws JMSException
      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:
      JMSException - if thrown by JMS API methods

    • refreshSharedConnection

      protected final void refreshSharedConnection() throws JMSException
      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:
      JMSException - if thrown by JMS API methods

    • createSharedConnection

      protected Connection createSharedConnection() throws JMSException
      Create a shared Connection for this container.

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

      Returns:
      the prepared Connection
      Throws:
      JMSException - if the creation failed

    • prepareSharedConnection

      protected void prepareSharedConnection(Connection connection) throws JMSException
      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:
      JMSException - if the preparation efforts failed
      See Also:

    • startSharedConnection

      protected void startSharedConnection() throws JMSException
      Start the shared Connection.
      Throws:
      JMSException - if thrown by JMS API methods
      See Also:

    • stopSharedConnection

      protected void stopSharedConnection() throws JMSException
      Stop the shared Connection.
      Throws:
      JMSException - if thrown by JMS API methods
      See Also:

    • getSharedConnection

      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:

    • rescheduleTaskIfNecessary

      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:

    • resumePausedTasks

      protected void resumePausedTasks()
      Try to resume all paused tasks. Tasks for which rescheduling failed simply remain in paused mode.

    • getPausedTaskCount

      public int getPausedTaskCount()
      Determine the number of currently paused tasks, if any.

    • doRescheduleTask

      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:

    • logRejectedTask

      protected void logRejectedTask(Object task, RuntimeException ex)
      Log a task that has been rejected by doRescheduleTask(java.lang.Object).

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

      Parameters:
      task - the rejected task object
      ex - the exception thrown from doRescheduleTask(java.lang.Object)

    • sharedConnectionEnabled

      protected abstract boolean sharedConnectionEnabled()
      Return whether a shared JMS Connection should be maintained by this container base class.
      See Also:

    • doInitialize

      protected abstract void doInitialize() throws JMSException
      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:
      JMSException - if registration failed
      See Also:

    • doShutdown

      protected abstract void doShutdown() throws JMSException
      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:
      JMSException - if shutdown failed
      See Also: