org.springframework.jms.annotation

Annotation Type EnableJms

@Target(value=TYPE)
 @Retention(value=RUNTIME)
 @Documented
 @Import(value=JmsBootstrapConfiguration.class)
public @interface EnableJms

Enable JMS listener annotated endpoints that are created under the cover by a JmsListenerContainerFactory. To be used on Configuration classes as follows:

 @Configuration
 @EnableJms
 public class AppConfig {

     @Bean
     public DefaultJmsListenerContainerFactory myJmsListenerContainerFactory() {
       DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory();
       factory.setConnectionFactory(connectionFactory());
       factory.setDestinationResolver(destinationResolver());
       factory.setSessionTransacted(true);
       factory.setConcurrency("5");
       return factory;
     }

     // other @Bean definitions
 }

The JmsListenerContainerFactory is responsible to create the listener container responsible for a particular endpoint. Typical implementations, as the DefaultJmsListenerContainerFactory used in the sample above, provides the necessary configuration options that are supported by the underlying MessageListenerContainer.

@EnableJms enables detection of JmsListener annotations on any Spring-managed bean in the container. For example, given a class MyService:

 package com.acme.foo;

 public class MyService {

     @JmsListener(containerFactory = "myJmsListenerContainerFactory", destination="myQueue")
     public void process(String msg) {
         // process incoming message
     }
 }

The container factory to use is identified by the containerFactory attribute defining the name of the JmsListenerContainerFactory bean to use. When none is set a JmsListenerContainerFactory bean with name jmsListenerContainerFactory is assumed to be present.

the following configuration would ensure that every time a Message is received on the Destination named "myQueue", MyService.process() is called with the content of the message:

 @Configuration
 @EnableJms
 public class AppConfig {

     @Bean
     public MyService myService() {
         return new MyService();
     }

     // JMS infrastructure setup
 }

Alternatively, if MyService were annotated with @Component, the following configuration would ensure that its @JmsListener annotated method is invoked with a matching incoming message:

 @Configuration
 @EnableJms
 @ComponentScan(basePackages="com.acme.foo")
 public class AppConfig {
 }

Note that the created containers are not registered against the application context but can be easily located for management purposes using the JmsListenerEndpointRegistry.

Annotated methods can use flexible signature; in particular, it is possible to use the Message abstraction and related annotations, see JmsListener Javadoc for more details. For instance, the following would inject the content of the message and a custom "myCounter" JMS header:

 @JmsListener(containerFactory = "myJmsListenerContainerFactory", destination="myQueue")
 public void process(String msg, @Header("myCounter") int counter) {
     // process incoming message
 }

These features are abstracted by the MessageHandlerMethodFactory that is responsible to build the necessary invoker to process the annotated method. By default, DefaultMessageHandlerMethodFactory is used.

When more control is desired, a @Configuration class may implement JmsListenerConfigurer. This allows access to the underlying JmsListenerEndpointRegistrar instance. The following example demonstrates how to specify an explicit default JmsListenerContainerFactory

 @Configuration
 @EnableJms
 public class AppConfig implements JmsListenerConfigurer {

     @Override
     public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) {
         registrar.setContainerFactory(myJmsListenerContainerFactory());
     }

     @Bean
     public JmsListenerContainerFactory<?> myJmsListenerContainerFactory() {
         // factory settings
     }

     @Bean
     public MyService myService() {
         return new MyService();
     }
 }

For reference, the example above can be compared to the following Spring XML configuration:

 <beans>

     <jms:annotation-driven container-factory="myJmsListenerContainerFactory"/>

     <bean id="myJmsListenerContainerFactory" class="org.springframework.jms.config.DefaultJmsListenerContainerFactory">
           // factory settings
     </bean>

     <bean id="myService" class="com.acme.foo.MyService"/>

 </beans>
 }

It is also possible to specify a custom JmsListenerEndpointRegistry in case you need more control on the way the containers are created and managed. The example below also demonstrates how to customize the JmsHandlerMethodFactory to use with a custom Validator so that payloads annotated with Validated are first validated against a custom Validator.

 @Configuration
 @EnableJms
 public class AppConfig implements JmsListenerConfigurer {

     @Override
     public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) {
         registrar.setEndpointRegistry(myJmsListenerEndpointRegistry());
         registrar.setMessageHandlerMethodFactory(myJmsHandlerMethodFactory);
     }

     @Bean
     public JmsListenerEndpointRegistry<?> myJmsListenerEndpointRegistry() {
         // registry configuration
     }

     @Bean
     public JmsHandlerMethodFactory myJmsHandlerMethodFactory() {
        DefaultJmsHandlerMethodFactory factory = new DefaultJmsHandlerMethodFactory();
        factory.setValidator(new MyValidator());
        return factory;
     }

     @Bean
     public MyService myService() {
         return new MyService();
     }
 }

For reference, the example above can be compared to the following Spring XML configuration:

 <beans>

     <jms:annotation-driven registry="myJmsListenerEndpointRegistry"
         handler-method-factory="myJmsHandlerMethodFactory"/>

     <bean id="myJmsListenerEndpointRegistry"
           class="org.springframework.jms.config.JmsListenerEndpointRegistry">
           // registry configuration
     </bean>

     <bean id="myJmsHandlerMethodFactory"
           class="org.springframework.messaging.handler.support.DefaultJmsHandlerMethodFactory">
         <property name="validator" ref="myValidator"/>
     </bean>

     <bean id="myService" class="com.acme.foo.MyService"/>

 </beans>
 

Implementing JmsListenerConfigurer also allows for fine-grained control over endpoints registration via the JmsListenerEndpointRegistrar. For example, the following configures an extra endpoint:

 @Configuration
 @EnableJms
 public class AppConfig implements JmsListenerConfigurer {

     @Override
     public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) {
         SimpleJmsListenerEndpoint myEndpoint = new SimpleJmsListenerEndpoint();
         // ... configure the endpoint
         registrar.registerEndpoint(endpoint, anotherJmsListenerContainerFactory());
     }

     @Bean
     public MyService myService() {
         return new MyService();
     }

     @Bean
     public JmsListenerContainerFactory<?> anotherJmsListenerContainerFactory() {
         // ...
     }

     // JMS infrastructure setup
 }

Note that all beans implementing JmsListenerConfigurer will be detected and invoked in a similar fashion. The example above can be translated in a regular bean definition registered in the context in case you use the XML configuration.

Since:

4.1

Author:

Stephane Nicoll

See Also:

JmsListener, JmsListenerAnnotationBeanPostProcessor, JmsListenerEndpointRegistrar, JmsListenerEndpointRegistry