spring-framework / org.springframework.jms.annotation

Package org.springframework.jms.annotation

Types

JmsListenerAnnotationBeanPostProcessor

 open class JmsListenerAnnotationBeanPostProcessor : MergedBeanDefinitionPostProcessor, Ordered, BeanFactoryAware, SmartInitializingSingleton

Bean post-processor that registers methods annotated with JmsListener to be invoked by a JMS message listener container created under the cover by a org.springframework.jms.config.JmsListenerContainerFactory according to the attributes of the annotation.

Annotated methods can use flexible arguments as defined by JmsListener.

This post-processor is automatically registered by Spring's <jms:annotation-driven> XML element, and also by the EnableJms annotation.

Autodetects any JmsListenerConfigurer instances in the container, allowing for customization of the registry to be used, the default container factory or for fine-grained control over endpoints registration. See the EnableJms javadocs for complete usage details.

JmsListenerConfigurer

 interface JmsListenerConfigurer

Optional interface to be implemented by a Spring managed bean willing to customize how JMS listener endpoints are configured. Typically used to define the default org.springframework.jms.config.JmsListenerContainerFactory to use or for registering JMS endpoints in a programmatic fashion as opposed to the declarative approach of using the @JmsListener annotation.

See @EnableJms for detailed usage examples.

Annotations

EnableJms

 class EnableJms

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

 @Configuration @EnableJms public class AppConfig { @Bean public DefaultJmsListenerContainerFactory myJmsListenerContainerFactory() { DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); factory.setConnectionFactory(connectionFactory()); factory.setDestinationResolver(destinationResolver()); 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 org.springframework.jms.config.DefaultJmsListenerContainerFactory used in the sample above, provides the necessary configuration options that are supported by the underlying org.springframework.jms.listener.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 javax.jms.Message is received on the javax.jms.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 org.springframework.jms.config.JmsListenerEndpointRegistry.

Annotated methods can use flexible signature; in particular, it is possible to use the org.springframework.messaging.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 org.springframework.messaging.handler.annotation.support.MessageHandlerMethodFactory that is responsible to build the necessary invoker to process the annotated method. By default, org.springframework.messaging.handler.annotation.support.DefaultMessageHandlerMethodFactory is used.

When more control is desired, a @Configuration class may implement JmsListenerConfigurer. This allows access to the underlying org.springframework.jms.config.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 org.springframework.jms.config.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 org.springframework.validation.Validator so that payloads annotated with org.springframework.validation.annotation.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"/&gt; <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.

JmsListeners

 class JmsListeners

Container annotation that aggregates several JmsListener annotations.

Can be used natively, declaring several nested JmsListener annotations. Can also be used in conjunction with Java 8's support for repeatable annotations, where JmsListener can simply be declared several times on the same method, implicitly generating this container annotation.

This annotation may be used as a meta-annotation to create custom composed annotations.