Package org.springframework.jms.annotation

Annotation Interface JmsListener

@Target({METHOD,ANNOTATION_TYPE}) @Retention(RUNTIME) @Documented @Repeatable(JmsListeners.class) @MessageMapping public @interface JmsListener
Annotation that marks a method to be the target of a JMS message listener on the specified destination(). The containerFactory() identifies the JmsListenerContainerFactory to use to build the JMS listener container. If not set, a default container factory is assumed to be available with a bean name of jmsListenerContainerFactory unless an explicit default has been provided through configuration.

Consider registering a custom DefaultJmsListenerContainerFactory bean. For production purposes, you'll typically fine tune timeouts and recovery settings. Most importantly, the default 'AUTO_ACKNOWLEDGE' mode does not provide reliability guarantees, so make sure to use transacted sessions in case of reliability needs.

Processing of @JmsListener annotations is performed by registering a JmsListenerAnnotationBeanPostProcessor. This can be done manually or, more conveniently, through the <jms:annotation-driven/> element or @EnableJms annotation.

Annotated JMS listener methods are allowed to have flexible signatures similar to what MessageMapping provides:

  • Session to get access to the JMS session
  • Message or one of its subclasses to get access to the raw JMS message
  • Message to use Spring's messaging abstraction counterpart
  • @Payload-annotated method arguments, including support for validation
  • @Header-annotated method arguments to extract specific header values, including standard JMS headers defined by JmsHeaders
  • @Headers-annotated method argument that must also be assignable to Map for obtaining access to all headers
  • MessageHeaders arguments for obtaining access to all headers
  • MessageHeaderAccessor or JmsMessageHeaderAccessor for convenient access to all method arguments

Annotated methods may have a non-void return type. When they do, the result of the method invocation is sent as a JMS reply to the destination defined by the JMSReplyTO header of the incoming message. If this header is not set, a default destination can be provided by adding @SendTo to the method declaration.

This annotation can be used as a repeatable annotation.

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

Since:
4.1
Author:
Stephane Nicoll, Sam Brannen
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    destination
    The destination name for this listener, resolved through the container-wide DestinationResolver strategy.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    concurrency
    The concurrency limits for the listener, if any.
    String
    containerFactory
    The bean name of the JmsListenerContainerFactory to use to create the message listener container responsible for serving this endpoint.
    String
    id
    The unique identifier of the container managing this endpoint.
    String
    selector
    The JMS message selector expression, if any.
    String
    subscription
    The name for the durable subscription, if any.

  • Element Details

    • destination

      String destination
      The destination name for this listener, resolved through the container-wide DestinationResolver strategy.

    • id

      String id
      The unique identifier of the container managing this endpoint.

      If none is specified, an auto-generated one is provided.

      See Also:
      Default:
      ""

    • containerFactory

      String containerFactory
      The bean name of the JmsListenerContainerFactory to use to create the message listener container responsible for serving this endpoint.

      If not specified, the default container factory is used, if any.

      Default:
      ""

    • subscription

      String subscription
      The name for the durable subscription, if any.

      As of Spring Framework 5.3.26, if an explicit subscription name is not specified, a default subscription name will be generated based on the fully qualified name of the annotated listener method — for example, "org.example.jms.ProductListener.processRequest" for a processRequest(...) listener method in the org.example.jms.ProductListener class.

      Default:
      ""

    • selector

      String selector
      The JMS message selector expression, if any.

      See the JMS specification for a detailed definition of selector expressions.

      Default:
      ""

    • concurrency

      String concurrency
      The concurrency limits for the listener, if any. Overrides the value defined by the container factory used to create the listener container.

      The concurrency limits can be a "lower-upper" String — for example, "5-10" — or a simple upper limit String — for example, "10", in which case the lower limit will be 1.

      Note that the underlying container may or may not support all features. For instance, it may not be able to scale, in which case only the upper limit is used.

      Default:
      ""