Package org.springframework.amqp.rabbit.annotation

Annotation Interface RabbitListener

@Target({TYPE,METHOD,ANNOTATION_TYPE}) @Retention(RUNTIME) @MessageMapping @Documented @Repeatable(RabbitListeners.class) public @interface RabbitListener
Annotation that marks a method to be the target of a Rabbit message listener on the specified queues() (or bindings()). The containerFactory() identifies the RabbitListenerContainerFactory to use to build the rabbit listener container. If not set, a default container factory is assumed to be available with a bean name of rabbitListenerContainerFactory unless an explicit default has been provided through configuration.

Processing of @RabbitListener annotations is performed by registering a RabbitListenerAnnotationBeanPostProcessor. This can be done manually or, more conveniently, through the <rabbit:annotation-driven/> element or EnableRabbit annotation.

Annotated methods are allowed to have flexible signatures similar to what MessageMapping provides, that is

  • Channel to get access to the Channel
  • Message or one if subclass to get access to the raw AMQP message
  • Message to use the messaging abstraction counterpart
  • @Payload-annotated method arguments including the support of validation
  • @Header-annotated method arguments to extract a specific header value, including standard AMQP headers defined by AmqpHeaders
  • @Headers-annotated argument that must also be assignable to Map for getting access to all headers.
  • MessageHeaders arguments for getting access to all headers.
  • MessageHeaderAccessor or AmqpMessageHeaderAccessor 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 reply to the queue defined by the ReplyTo header of the incoming message. When this value is not set, a default queue can be provided by adding @SendTo to the method declaration.

When bindings() are provided, and the application context contains a RabbitAdmin, the queue, exchange and binding will be automatically declared.

When defined at the method level, a listener container is created for each method. The MessageListener is a MessagingMessageListenerAdapter, configured with a MethodRabbitListenerEndpoint.

When defined at the class level, a single message listener container is used to service all methods annotated with @RabbitHandler. Method signatures of such annotated methods must not cause any ambiguity such that a single method can be resolved for a particular inbound message. The MessagingMessageListenerAdapter is configured with a MultiMethodRabbitListenerEndpoint.

Since:
1.4
Author:
Stephane Nicoll, Gary Russell
See Also:

  • Element Details

    • id

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

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

      Returns:
      the id for the container managing for this endpoint.
      See Also:
      Default:
      ""

    • containerFactory

      String containerFactory
      The bean name of the RabbitListenerContainerFactory to use to create the message listener container responsible to serve this endpoint.

      If not specified, the default container factory is used, if any. If a SpEL expression is provided (#{...}), the expression can either evaluate to a container factory instance or a bean name.

      Returns:
      the RabbitListenerContainerFactory bean name.
      Default:
      ""

    • queues

      String[] queues
      The queues for this listener. The entries can be 'queue name', 'property-placeholder keys' or 'expressions'. Expression must be resolved to the queue name or Queue object. The queue(s) must exist, or be otherwise defined elsewhere as a bean(s) with a RabbitAdmin in the application context. Mutually exclusive with bindings() and queuesToDeclare().
      Returns:
      the queue names or expressions (SpEL) to listen to from target
      See Also:
      Default:
      {}

    • queuesToDeclare

      Queue[] queuesToDeclare
      The queues for this listener. If there is a RabbitAdmin in the application context, the queue will be declared on the broker with default binding (default exchange with the queue name as the routing key). Mutually exclusive with bindings() and queues(). NOTE: Broker-named queues cannot be declared this way, they must be defined as beans (with an empty string for the name).
      Returns:
      the queue(s) to declare.
      Since:
      2.0
      See Also:
      Default:
      {}

    • exclusive

      boolean exclusive
      When true, a single consumer in the container will have exclusive use of the queues(), preventing other consumers from receiving messages from the queues. When true, requires a concurrency of 1. Default false.
      Returns:
      the exclusive boolean flag.
      Default:
      false

    • priority

      String priority
      The priority of this endpoint. Requires RabbitMQ 3.2 or higher. Does not change the container priority by default. Larger numbers indicate higher priority, and both positive and negative numbers can be used.
      Returns:
      the priority for the endpoint.
      Default:
      ""

    • admin

      String admin
      Reference to a AmqpAdmin. Required if the listener is using auto-delete queues and those queues are configured for conditional declaration. This is the admin that will (re)declare those queues when the container is (re)started. See the reference documentation for more information. If a SpEL expression is provided (#{...}) the expression can evaluate to an AmqpAdmin instance or bean name.
      Returns:
      the AmqpAdmin bean name.
      Default:
      ""

    • bindings

      QueueBinding[] bindings
      Array of QueueBindings providing the listener's queue names, together with the exchange and optional binding information. Mutually exclusive with queues() and queuesToDeclare(). NOTE: Broker-named queues cannot be declared this way, they must be defined as beans (with an empty string for the name).
      Returns:
      the bindings.
      Since:
      1.5
      See Also:
      Default:
      {}

    • group

      String group
      If provided, the listener container for this listener will be added to a bean with this value as its name, of type Collection<MessageListenerContainer>. This allows, for example, iteration over the collection to start/stop a subset of containers.
      Returns:
      the bean name for the group.
      Since:
      1.5
      Default:
      ""

    • returnExceptions

      String returnExceptions
      Set to "true" to cause exceptions thrown by the listener to be sent to the sender using normal replyTo/@SendTo semantics. When false, the exception is thrown to the listener container and normal retry/DLQ processing is performed.
      Returns:
      true to return exceptions. If the client side uses a RemoteInvocationAwareMessageConverterAdapter the exception will be re-thrown. Otherwise, the sender will receive a RemoteInvocationResult wrapping the exception.
      Since:
      2.0
      Default:
      ""

    • errorHandler

      String errorHandler
      Set an RabbitListenerErrorHandler to invoke if the listener method throws an exception. A simple String representing the bean name. If a Spel expression (#{...}) is provided, the expression must evaluate to a bean name or a RabbitListenerErrorHandler instance.
      Returns:
      the error handler.
      Since:
      2.0
      Default:
      ""

    • concurrency

      String concurrency
      Set the concurrency of the listener container for this listener. Overrides the default set by the listener container factory. Maps to the concurrency setting of the container type.

      For a SimpleMessageListenerContainer if this value is a simple integer, it sets a fixed number of consumers in the concurrentConsumers property. If it is a string with the form "m-n", the concurrentConsumers is set to m and the maxConcurrentConsumers is set to n.

      For a DirectMessageListenerContainer it sets the consumersPerQueue property.

      Returns:
      the concurrency.
      Since:
      2.0
      Default:
      ""

    • autoStartup

      String autoStartup
      Set to true or false, to override the default setting in the container factory.
      Returns:
      true to auto start, false to not auto start.
      Since:
      2.0
      Default:
      ""

    • executor

      String executor
      Set the task executor bean name to use for this listener's container; overrides any executor set on the container factory. If a SpEL expression is provided (#{...}), the expression can either evaluate to a executor instance or a bean name.
      Returns:
      the executor bean name.
      Since:
      2.2
      Default:
      ""

    • ackMode

      String ackMode
      Override the container factory AcknowledgeMode property. Must be one of the valid enumerations. If a SpEL expression is provided, it must evaluate to a String or AcknowledgeMode.
      Returns:
      the acknowledgement mode.
      Since:
      2.2
      Default:
      ""

    • replyPostProcessor

      String replyPostProcessor
      The bean name of a ReplyPostProcessor to post process a response before it is sent. If a SpEL expression is provided (#{...}), the expression can either evaluate to a post processor instance or a bean name.
      Returns:
      the bean name.
      Since:
      2.2.5
      See Also:
      Default:
      ""

    • messageConverter

      String messageConverter
      Override the container factory's message converter used for this listener.
      Returns:
      the message converter bean name. If a SpEL expression is provided (#{...}), the expression can either evaluate to a converter instance or a bean name.
      Since:
      2.3
      Default:
      ""

    • replyContentType

      String replyContentType
      Used to set the content type of a reply message. Useful when used in conjunction with message converters that can handle multiple content types, such as the ContentTypeDelegatingMessageConverter. SpEL expressions and property placeholders are supported. Also useful if you wish to control the final content type property when used with certain converters. This does not apply when the return type is Message or Message; set the content type message property or header respectively, in those cases.
      Returns:
      the content type.
      Since:
      2.3
      See Also:
      Default:
      ""

    • converterWinsContentType

      String converterWinsContentType
      Set to 'false' to override any content type headers set by the message converter with the value of the 'replyContentType' property. Some converters, such as the SimpleMessageConverter use the payload type and set the content type header appropriately. For example, if you set the 'replyContentType' to "application/json" and use the simple message converter when returning a String containing JSON, the converter will overwrite the content type to 'text/plain'. Set this to false, to prevent that action. This does not apply when the return type is Message because there is no conversion involved. When returning a Message, set the content type message header and AmqpHeaders.CONTENT_TYPE_CONVERTER_WINS to false.
      Returns:
      false to use the replyContentType.
      Since:
      2.3
      See Also:
      Default:
      "true"

    • batch

      String batch
      Override the container factory's batchListener property. The listener method signature should receive a List<?>; refer to the reference documentation. This allows a single container factory to be used for both record and batch listeners; previously separate container factories were required.
      Returns:
      "true" for the annotated method to be a batch listener or "false" for a single message listener. If not set, the container factory setting is used. SpEL and property place holders are not supported because the listener type cannot be variable.
      Since:
      3.0
      See Also:
      Default:
      ""