AbstractJmsListeningContainer (Spring Framework API 2.1) - Spring Framework 2.1.0 API 文档英文版

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

The Spring Framework

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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:: BeanNameAware, DisposableBean, InitializingBean, Lifecycle

Direct Known Subclasses:: AbstractMessageListenerContainer

public abstract class AbstractJmsListeningContainer
extends JmsDestinationAccessor
implements Lifecycle, BeanNameAware, DisposableBean
extends JmsDestinationAccessor
implements Lifecycle, BeanNameAware, DisposableBean

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:: sharedConnectionEnabled(), doInitialize(), doShutdown()

Nested Class Summary

static class AbstractJmsListeningContainer.SharedConnectionNotInitializedException
          Exception that indicates that the initial setup of this container's shared JMS Connection failed.

Field Summary

Fields inherited from class org.springframework.jms.support.JmsAccessor

logger

Constructor Summary

AbstractJmsListeningContainer()


Method Summary

void afterPropertiesSet()
          Delegates to validateConfiguration() and initialize().

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

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

protected abstract void doInitialize()
          Register any invokers within this container.

protected void doRescheduleTask(Object task)
          Reschedule the given task object immediately.

protected abstract void doShutdown()
          Close the registered invokers.

protected void doStart()
          Start the shared Connection, if any, and notify all invoker tasks.

protected void doStop()
          Notify all invoker tasks and stop the shared Connection, if any.

protected void establishSharedConnection()
          Establish a shared Connection for this container.

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

protected Connection getSharedConnection()
          Return the shared JMS Connection maintained by this container.

void initialize()
          Initialize this container.

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

boolean isRunning()
          Return whether this container is currently running, that is, whether it has been started and not stopped yet.

protected void prepareSharedConnection(Connection connection)
          Prepare the given Connection, which is about to be registered as shared Connection for this container.

protected void refreshSharedConnection()
          Refresh the shared Connection that this container holds.

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

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

protected void startSharedConnection()
          Start the shared Connection.

void stop()
          Stop this container.

protected void stopSharedConnection()
          Stop the shared Connection.

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

protected void waitWhileNotRunning()
          Wait while this container is not running.

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

Nested Class Summary
`static class`	`AbstractJmsListeningContainer.SharedConnectionNotInitializedException` Exception that indicates that the initial setup of this container's shared JMS Connection failed.

Fields inherited from class org.springframework.jms.support.JmsAccessor
`logger`

Constructor Summary
`AbstractJmsListeningContainer()`

Method Summary
`void`	`afterPropertiesSet()` Delegates to `validateConfiguration()` and `initialize()`.
`protected Connection`	`createSharedConnection()` Create a shared Connection for this container.
`void`	`destroy()` Calls `shutdown()` when the BeanFactory destroys the container instance.
`protected abstract void`	`doInitialize()` Register any invokers within this container.
`protected void`	`doRescheduleTask(Object task)` Reschedule the given task object immediately.
`protected abstract void`	`doShutdown()` Close the registered invokers.
`protected void`	`doStart()` Start the shared Connection, if any, and notify all invoker tasks.
`protected void`	`doStop()` Notify all invoker tasks and stop the shared Connection, if any.
`protected void`	`establishSharedConnection()` Establish a shared Connection for this container.
`protected 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.
`protected Connection`	`getSharedConnection()` Return the shared JMS Connection maintained by this container.
`void`	`initialize()` Initialize this container.
`boolean`	`isActive()` Return whether this container is currently active, that is, whether it has been set up but not shut down yet.
`boolean`	`isRunning()` Return whether this container is currently running, that is, whether it has been started and not stopped yet.
`protected void`	`prepareSharedConnection(Connection connection)` Prepare the given Connection, which is about to be registered as shared Connection for this container.
`protected void`	`refreshSharedConnection()` Refresh the shared Connection that this container holds.
`protected 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`	`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.
`protected 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.
`protected void`	`startSharedConnection()` Start the shared Connection.
`void`	`stop()` Stop this container.
`protected void`	`stopSharedConnection()` Stop the shared Connection.
`protected void`	`validateConfiguration()` Validate the configuration of this container.
`protected void`	`waitWhileNotRunning()` Wait while this container is not running.

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

AbstractJmsListeningContainer

public AbstractJmsListeningContainer()

Method Detail

setClientId

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:: Connection.setClientID(java.lang.String), JmsAccessor.setConnectionFactory(javax.jms.ConnectionFactory)

getClientId

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.

setBeanName

public void setBeanName(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

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.

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

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 proces 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 occured 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(javax.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:: getClientId()

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:: sharedConnectionEnabled()

destroy

public void destroy()

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

Specified by:: destroy in interface DisposableBean

See Also:: shutdown()

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

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:: startSharedConnection()

startSharedConnection

protected void startSharedConnection()
                              throws JMSException

Start the shared Connection.

Throws:: JMSException - if thrown by JMS API methods
See Also:: Connection.start()

stop

public void stop()
          throws JmsException

Stop this container.

Specified by:: stop in interface Lifecycle

Throws:: JmsException - if stopping failed
See Also:: doStop()

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:: stopSharedConnection()

stopSharedConnection

protected void stopSharedConnection()
                             throws JMSException

Stop the shared Connection.

Throws:: JMSException - if thrown by JMS API methods
See Also:: Connection.start()

isRunning

public final boolean isRunning()

Return 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

waitWhileNotRunning

protected final void waitWhileNotRunning()

Wait while this container is not running.

To be called by asynchronous tasks that want to block while the container is in stopped state.

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:: doRescheduleTask(java.lang.Object)

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:: rescheduleTaskIfNecessary(java.lang.Object)

sharedConnectionEnabled

protected abstract boolean sharedConnectionEnabled()

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

See Also:: getSharedConnection()

doInitialize

protected abstract void doInitialize()
                              throws JMSException

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:: getSharedConnection()

doShutdown

protected abstract void doShutdown()
                            throws JMSException

Close the registered invokers.