Default JmsListenerContainerFactory lookup

Prior to this commit, the default JmsListenerContainerFactory to use
must be explicitly set. Since having a single container factory is a
fairly common use case, we look up the default one automatically
using the bean name "jmsListenerContainerFactory".

It is still possible to provide an explicit default but since it refers
more to "the" container factory to use, the parameter has been
renamed to "containerFactory" which is shorter and more explicit.

The lookup strategy is lazy: if all endpoints are providing an
explicit container factory and no container factory with the
"jmsListenerContainerFactory" bean name exists, no exception
will be thrown.

Issue : SPR-11706

Author: snicoll

spring-jms/src/main/java/org/springframework/jms/annotation/EnableJms.java

@@ -66,7 +66,9 @@
  * }</pre>
  *
  * The container factory to use is identified by the {@link JmsListener#containerFactory() containerFactory}
- * attribute defining the name of the {@code JmsListenerContainerFactory} bean to use.
+ * attribute defining the name of the {@code JmsListenerContainerFactory} bean to use.  When none
+ * is set a {@code JmsListenerContainerFactory} bean with name {@code jmsListenerContainerFactory} is
+ * assumed to be present.
  *
  * <p>the following configuration would ensure that every time a {@link javax.jms.Message}
  * is received on the {@link javax.jms.Destination} named "myQueue", {@code MyService.process()}
@@ -118,17 +120,16 @@
  * <p>When more control is desired, a {@code @Configuration} class may implement
  * {@link JmsListenerConfigurer}. This allows access to the underlying
  * {@link org.springframework.jms.config.JmsListenerEndpointRegistrar JmsListenerEndpointRegistrar}
- * instance. The following example demonstrates how to specify a default
- * {@code JmsListenerContainerFactory} so that {@link JmsListener#containerFactory()} may be
- * omitted for endpoints willing to use the <em>default</em> container factory.
+ * instance. The following example demonstrates how to specify an explicit default
+ * {@code JmsListenerContainerFactory}
  *
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableJms
  * public class AppConfig implements JmsListenerConfigurer {
  *     &#064;Override
  *     public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) {
- *         registrar.setDefaultContainerFactory(myJmsListenerContainerFactory());
+ *         registrar.setContainerFactory(myJmsListenerContainerFactory());
  *     }
  *
  *     &#064;Bean
@@ -146,7 +147,7 @@
  * configuration:
  * <pre class="code">
  * {@code <beans>
- *     <jms:annotation-driven default-container-factory="myJmsListenerContainerFactory"/>
+ *     <jms:annotation-driven container-factory="myJmsListenerContainerFactory"/>
  *
  *     <bean id="myJmsListenerContainerFactory"
  *           class="org.springframework.jms.config.DefaultJmsListenerContainerFactory">

spring-jms/src/main/java/org/springframework/jms/annotation/JmsListener.java

@@ -28,8 +28,10 @@
  * Annotation that marks a method to be the target of a JMS message
  * listener on the specified {@link #destination()}. The {@link #containerFactory()}
  * identifies the {@link org.springframework.jms.config.JmsListenerContainerFactory
- * JmsListenerContainerFactory} to use to build the jms listener container. It may
- * be omitted as long as a <em>default</em> container factory has been defined.
+ * JmsListenerContainerFactory} to use to build the jms listener container. If not
+ * set, a <em>default</em> container factory is assumed to be available with a bean
+ * name of {@code jmsListenerContainerFactory} unless an explicit default has been
+ * provided through configuration.
  *
  * <p>Processing of {@code @JmsListener} annotations is performed by
  * registering a {@link JmsListenerAnnotationBeanPostProcessor}. This can be

spring-jms/src/main/java/org/springframework/jms/annotation/JmsListenerAnnotationBeanPostProcessor.java

@@ -73,13 +73,18 @@
 public class JmsListenerAnnotationBeanPostProcessor implements BeanPostProcessor, Ordered,
 		ApplicationContextAware, ApplicationListener<ContextRefreshedEvent> {
 
+	/**
+	 * The bean name of the default {@link JmsListenerContainerFactory}
+	 */
+	static final String DEFAULT_JMS_LISTENER_CONTAINER_FACTORY_BEAN_NAME = "jmsListenerContainerFactory";
+
 	private final AtomicInteger counter = new AtomicInteger();
 
 	private ApplicationContext applicationContext;
 
 	private JmsListenerEndpointRegistry endpointRegistry;
 
-	private JmsListenerContainerFactory<?> defaultContainerFactory;
+	private String containerFactoryBeanName = DEFAULT_JMS_LISTENER_CONTAINER_FACTORY_BEAN_NAME;
 
 	private final JmsHandlerMethodFactoryAdapter jmsHandlerMethodFactory = new JmsHandlerMethodFactoryAdapter();
 
@@ -99,12 +104,12 @@ public void setEndpointRegistry(JmsListenerEndpointRegistry endpointRegistry) {
 	}
 
 	/**
-	 * Set the default {@link JmsListenerContainerFactory} to use in case a
-	 * {@link JmsListener} does not define any.
-	 * {@linkplain JmsListener#containerFactory() containerFactory}
+	 * Set the name of the {@link JmsListenerContainerFactory} to use by default.
+	 * <p/>If none is specified, {@value #DEFAULT_JMS_LISTENER_CONTAINER_FACTORY_BEAN_NAME}
+	 * is assumed to be defined.
 	 */
-	public void setDefaultContainerFactory(JmsListenerContainerFactory<?> defaultContainerFactory) {
-		this.defaultContainerFactory = defaultContainerFactory;
+	public void setContainerFactoryBeanName(String containerFactoryBeanName) {
+		this.containerFactoryBeanName = containerFactoryBeanName;
 	}
 
 	/**
@@ -209,6 +214,9 @@ public void onApplicationEvent(ContextRefreshedEvent event) {
 		for (JmsListenerConfigurer configurer : instances.values()) {
 			configurer.configureJmsListeners(registrar);
 		}
+
+		registrar.setApplicationContext(this.applicationContext);
+
 		if (registrar.getEndpointRegistry() == null) {
 			if (endpointRegistry == null) {
 				endpointRegistry = applicationContext
@@ -217,10 +225,13 @@ public void onApplicationEvent(ContextRefreshedEvent event) {
 			}
 			registrar.setEndpointRegistry(endpointRegistry);
 		}
-		if (registrar.getDefaultContainerFactory() == null && defaultContainerFactory != null) {
-			registrar.setDefaultContainerFactory(defaultContainerFactory);
+
+		if (this.containerFactoryBeanName != null) {
+			registrar.setContainerFactoryBeanName(this.containerFactoryBeanName);
 		}
 
+
+		// Set the custom handler method factory once resolved by the configurer
 		JmsHandlerMethodFactory handlerMethodFactory = registrar.getJmsHandlerMethodFactory();
 		if (handlerMethodFactory != null) {
 			this.jmsHandlerMethodFactory.setJmsHandlerMethodFactory(handlerMethodFactory);
@@ -235,7 +246,6 @@ public void onApplicationEvent(ContextRefreshedEvent event) {
 		}
 	}
 
-
 	private String getEndpointId(JmsListener jmsListener) {
 		if (StringUtils.hasText(jmsListener.id())) {
 			return jmsListener.id();
@@ -267,7 +277,7 @@ public InvocableHandlerMethod createInvocableHandlerMethod(Object bean, Method m
 
 		private JmsHandlerMethodFactory getJmsHandlerMethodFactory() {
 			if (jmsHandlerMethodFactory == null) {
-				jmsHandlerMethodFactory= createDefaultJmsHandlerMethodFactory();
+				jmsHandlerMethodFactory = createDefaultJmsHandlerMethodFactory();
 			}
 			return jmsHandlerMethodFactory;
 		}

spring-jms/src/main/java/org/springframework/jms/config/AnnotationDrivenJmsBeanDefinitionParser.java

@@ -64,10 +64,12 @@ public BeanDefinition parse(Element element, ParserContext parserContext) {
 			else {
 				registerDefaultEndpointRegistry(source, parserContext);
 			}
-			String defaultContainerFactory = element.getAttribute("default-container-factory");
-			if (StringUtils.hasText(defaultContainerFactory)) {
-				builder.addPropertyReference("defaultContainerFactory", defaultContainerFactory);
+
+			String containerFactory = element.getAttribute("container-factory");
+			if (StringUtils.hasText(containerFactory)) {
+				builder.addPropertyValue("containerFactoryBeanName", containerFactory);
 			}
+
 			String handlerMethodFactory = element.getAttribute("handler-method-factory");
 			if (StringUtils.hasText(handlerMethodFactory)) {
 				builder.addPropertyReference("jmsHandlerMethodFactory", handlerMethodFactory);

spring-jms/src/main/java/org/springframework/jms/config/JmsListenerEndpointRegistrar.java

@@ -20,6 +20,8 @@
 import java.util.List;
 
 import org.springframework.beans.factory.InitializingBean;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.ApplicationContextAware;
 import org.springframework.util.Assert;
 
 /**
@@ -30,14 +32,18 @@
  * @since 4.1
  * @see org.springframework.jms.annotation.JmsListenerConfigurer
  */
-public class JmsListenerEndpointRegistrar implements InitializingBean {
+public class JmsListenerEndpointRegistrar implements ApplicationContextAware, InitializingBean {
 
 	private JmsListenerEndpointRegistry endpointRegistry;
 
-	private JmsListenerContainerFactory<?> defaultContainerFactory;
+	private String containerFactoryBeanName;
+
+	private JmsListenerContainerFactory<?> containerFactory;
 
 	private JmsHandlerMethodFactory jmsHandlerMethodFactory;
 
+	private ApplicationContext applicationContext;
+
 	private final List<JmsListenerEndpointDescriptor> endpointDescriptors
 			= new ArrayList<JmsListenerEndpointDescriptor>();
 
@@ -57,20 +63,24 @@ public JmsListenerEndpointRegistry getEndpointRegistry() {
 	}
 
 	/**
-	 * Set the default {@link JmsListenerContainerFactory} to use in case a
-	 * {@link JmsListenerEndpoint} is registered with a {@code null} container
-	 * factory.
+	 * Set the bean name of the {@link JmsListenerContainerFactory} to use in
+	 * case a {@link JmsListenerEndpoint} is registered with a {@code null}
+	 * container factory. Alternatively, the container factory instance can
+	 * be registered directly, see {@link #setContainerFactory(JmsListenerContainerFactory)}
 	 */
-	public void setDefaultContainerFactory(JmsListenerContainerFactory<?> defaultContainerFactory) {
-		this.defaultContainerFactory = defaultContainerFactory;
+	public void setContainerFactoryBeanName(String containerFactoryBeanName) {
+		this.containerFactoryBeanName = containerFactoryBeanName;
 	}
 
 	/**
-	 * Return the {@link JmsListenerContainerFactory} to use if none has been
-	 * defined for a particular endpoint or {@code null} if no default is set.
+	 * Set the {@link JmsListenerContainerFactory} to use in case a
+	 * {@link JmsListenerEndpoint} is registered with a {@code null} container
+	 * factory.
+	 * <p>Alternatively, the bean name of the {@link JmsListenerContainerFactory}
+	 * to use can be specified for a lazy lookup, see {@see #setContainerFactoryBeanName}
 	 */
-	public JmsListenerContainerFactory<?> getDefaultContainerFactory() {
-		return defaultContainerFactory;
+	public void setContainerFactory(JmsListenerContainerFactory<?> containerFactory) {
+		this.containerFactory = containerFactory;
 	}
 
 	/**
@@ -92,6 +102,11 @@ public JmsHandlerMethodFactory getJmsHandlerMethodFactory() {
 		return jmsHandlerMethodFactory;
 	}
 
+	@Override
+	public void setApplicationContext(ApplicationContext applicationContext) {
+		this.applicationContext = applicationContext;
+	}
+
 	/**
 	 * Register a new {@link JmsListenerEndpoint} alongside the {@link JmsListenerContainerFactory}
 	 * to use to create the underlying container.
@@ -109,7 +124,7 @@ public void registerEndpoint(JmsListenerEndpoint endpoint, JmsListenerContainerF
 	 * Register a new {@link JmsListenerEndpoint} using the default {@link JmsListenerContainerFactory}
 	 * to create the underlying container.
 	 *
-	 * @see #setDefaultContainerFactory(JmsListenerContainerFactory)
+	 * @see #setContainerFactory(JmsListenerContainerFactory)
 	 * @see #registerEndpoint(JmsListenerEndpoint, JmsListenerContainerFactory)
 	 */
 	public void registerEndpoint(JmsListenerEndpoint endpoint) {
@@ -118,6 +133,7 @@ public void registerEndpoint(JmsListenerEndpoint endpoint) {
 
 	@Override
 	public void afterPropertiesSet() throws Exception {
+	 	Assert.notNull(applicationContext, "ApplicationContext must not be null");
 		startAllEndpoints();
 	}
 
@@ -132,8 +148,13 @@ private JmsListenerContainerFactory<?> resolveContainerFactory(JmsListenerEndpoi
 		if (descriptor.containerFactory != null) {
 			return descriptor.containerFactory;
 		}
-		else if (defaultContainerFactory != null) {
-			return defaultContainerFactory;
+		else if (this.containerFactory != null) {
+			return this.containerFactory;
+		}
+		else if (this.containerFactoryBeanName != null) {
+			this.containerFactory =  applicationContext.getBean(
+					this.containerFactoryBeanName, JmsListenerContainerFactory.class);
+			return this.containerFactory; // Consider changing this if live change of the factory is required
 		}
 		else {
 			throw new IllegalStateException("Could not resolve the "

spring-jms/src/main/resources/org/springframework/jms/config/spring-jms-4.1.xsd

@@ -43,13 +43,15 @@
 					</xsd:appinfo>
 				</xsd:annotation>
 			</xsd:attribute>
-			<xsd:attribute name="default-container-factory" type="xsd:string" use="optional">
+			<xsd:attribute name="container-factory" type="xsd:string" use="optional">
 				<xsd:annotation>
 					<xsd:documentation><![CDATA[
-	Specifies the default org.springframework.jms.config.JmsListenerContainerFactory instance to
+	Specifies the org.springframework.jms.config.JmsListenerContainerFactory instance to
 	use to create the container for a jms listener endpoint that does not define a specific
 	factory. This permits in practice to omit the "containerFactory" attribute of the JmsListener
-	annotation. If not provided, each endpoint must define the container factory to use.
+	annotation. This attribute is not required as each endpoint may define the factory to use and,
+	as a convenience, the JmsListenerContainerFactory with name 'jmsListenerContainerFactory' is
+	looked up by default.
 					]]></xsd:documentation>
 					<xsd:appinfo>
 						<tool:annotation kind="ref">

spring-jms/src/test/java/org/springframework/jms/annotation/AbstractJmsAnnotationDrivenTests.java

@@ -59,17 +59,21 @@ public abstract class AbstractJmsAnnotationDrivenTests {
 	public abstract void customConfiguration();
 
 	@Test
-	public abstract void defaultContainerFactoryConfiguration();
+	public abstract void explicitContainerFactory();
+
+	@Test
+	public abstract void defaultContainerFactory();
 
 	@Test
 	public abstract void jmsHandlerMethodFactoryConfiguration() throws JMSException;
 
 	/**
-	 * Test for {@link SampleBean} discovery.
+	 * Test for {@link SampleBean} discovery. If a factory with the default name
+	 * is set, an endpoint will use it automatically
 	 */
 	public void testSampleConfiguration(ApplicationContext context) {
 		JmsListenerContainerTestFactory defaultFactory =
-				context.getBean("defaultFactory", JmsListenerContainerTestFactory.class);
+				context.getBean("jmsListenerContainerFactory", JmsListenerContainerTestFactory.class);
 		JmsListenerContainerTestFactory simpleFactory =
 				context.getBean("simpleFactory", JmsListenerContainerTestFactory.class);
 		assertEquals(1, defaultFactory.getContainers().size());
@@ -79,7 +83,7 @@ public void testSampleConfiguration(ApplicationContext context) {
 	@Component
 	static class SampleBean {
 
-		@JmsListener(containerFactory = "defaultFactory", destination = "myQueue")
+		@JmsListener(destination = "myQueue")
 		public void defaultHandle(String msg) {
 		}
 
@@ -89,7 +93,9 @@ public void simpleHandle(String msg) {
 	}
 
 	/**
-	 * Test for {@link FullBean} discovery.
+	 * Test for {@link FullBean} discovery. In this case, no default is set because
+	 * all endpoints provide a default registry. This shows that the default factory
+	 * is only retrieved if it needs to be.
 	 */
 	public void testFullConfiguration(ApplicationContext context) {
 		JmsListenerContainerTestFactory simpleFactory =
@@ -116,11 +122,12 @@ public String fullHandle(String msg) {
 
 	/**
 	 * Test for {@link CustomBean} and an manually endpoint registered
-	 * with "myCustomEndpointId".
+	 * with "myCustomEndpointId". The custom endpoint does not provide
+	 * any factory so it's registered with the default one
 	 */
 	public void testCustomConfiguration(ApplicationContext context) {
 		JmsListenerContainerTestFactory defaultFactory =
-				context.getBean("defaultFactory", JmsListenerContainerTestFactory.class);
+				context.getBean("jmsListenerContainerFactory", JmsListenerContainerTestFactory.class);
 		JmsListenerContainerTestFactory customFactory =
 				context.getBean("customFactory", JmsListenerContainerTestFactory.class);
 		assertEquals(1, defaultFactory.getContainers().size());
@@ -150,11 +157,22 @@ public void customHandle(String msg) {
 
 	/**
 	 * Test for {@link DefaultBean} that does not define the container
-	 * factory to use as a default is registered.
+	 * factory to use as a default is registered with an explicit
+	 * default.
+	 */
+	public void testExplicitContainerFactoryConfiguration(ApplicationContext context) {
+		JmsListenerContainerTestFactory defaultFactory =
+				context.getBean("simpleFactory", JmsListenerContainerTestFactory.class);
+		assertEquals(1, defaultFactory.getContainers().size());
+	}
+
+	/**
+	 * Test for {@link DefaultBean} that does not define the container
+	 * factory to use as a default is registered with the default name.
 	 */
 	public void testDefaultContainerFactoryConfiguration(ApplicationContext context) {
 		JmsListenerContainerTestFactory defaultFactory =
-				context.getBean("defaultFactory", JmsListenerContainerTestFactory.class);
+				context.getBean("jmsListenerContainerFactory", JmsListenerContainerTestFactory.class);
 		assertEquals(1, defaultFactory.getContainers().size());
 	}