2. Introduction

This first part of the reference documentation is a high-level overview of Spring AMQP and the underlying concepts and some code snippets that will get you up and running as quickly as possible.

2.1 Quick Tour for the impatient

2.1.1 Introduction

This is the 5 minute tour to get started with Spring AMQP.

Prerequisites: install and run the RabbitMQ broker (http://www.rabbitmq.com/download.html).
Then grab the spring-rabbit JAR and all its dependencies - the easiest way to do that is to declare a dependency in your build tool, e.g.
for Maven:

Compatibility

While the default Spring Framework version dependency is 4.2.x, Spring AMQP is generally compatible with earlier versions of Spring Framework.
Annotation-based listeners and the RabbitMessagingTemplate require Spring Framework 4.1 or higher, however.

Similarly, the default amqp-client version is 3.5.x but the framework is generally compatible with earlier versions.
However, of course, features that rely on newer client versions will not be available.

Note that there is a ConnectionFactory in the native Java Rabbit client as well.
We are using the Spring abstraction in the code above.
We are relying on the default exchange in the broker (since none is specified in the send), and the default binding of all queues to the default exchange by their name (hence we can use the queue name as a routing key in the send).
Those behaviours are defined in the AMQP specification.

With XML Configuration

The same example as above, but externalizing the resource configuration to XML:

The <rabbit:admin/> declaration by default automatically looks for beans of type Queue, Exchange and Binding and declares them to the broker on behalf of the user, hence there is no need to use that bean explicitly in the simple Java driver.
There are plenty of options to configure the properties of the components in the XML schema - you can use auto-complete features of your XML editor to explore them and look at their documentation.

2.2 What’s New

2.2.1 Changes in 1.5 Since 1.4

spring-erlang is No Longer Supported

CachingConnectionFactory Changes

Empty Addresses Property in CachingConnectionFactory

Previously, if the connection factory was configured with a host/port, but an empty String was also supplied for
addresses, the host and port were ignored.
Now, an empty addresses String is treated the same as a null, and the host/port will be used.

URI Constructor

The CachingConnectionFactory has an additional constructor, with a URI parameter, to configure the broker connection.

Connection Reset

A new method resetConnection() has been added to allow users to reset the connection (or connections).
This might be used, for example, to reconnect to the primary broker after failing over to the secondary broker.
This will impact in-process operations.
The existing destroy() method does exactly the same, but the new method has a less daunting name.

Properties to Control Container Queue Declaration Behavior

When the listener container consumers start, they attempt to passively declare the queues to ensure they are available
on the broker.
Previously, if these declarations failed, for example because the queues didn’t exist, or when an HA queue was being
moved, the retry logic was fixed at 3 retry attempts at 5 second intervals.
If the queue(s) still do not exist, the behavior is controlled by the missingQueuesFatal property (default true).
Also, for containers configured to listen from multiple queues, if only a subset of queues are available, the consumer
retried the missing queues on a fixed interval of 60 seconds.

Class Package Change

The RabbitGatewaySupport class has been moved from o.s.amqp.rabbit.core.support to o.s.amqp.rabbit.core.

DefaultMessagePropertiesConverter

The DefaultMessagePropertiesConverter can now be configured to
determine the maximum length of a LongString that will be converted
to a String rather than a DataInputStream.
The converter has an alternative constructor that takes the value as a limit.
Previously, this limit was hard-coded at 1024 bytes.
(Also available in 1.4.4).

@RabbitListener Improvements

@QueueBinding for @RabbitListener

The bindings attribute has been added to the @RabbitListener annotation as mutually exclusive with the queues
attribute to allow the specification of the queue, its exchange and binding for declaration by a RabbitAdmin on
the Broker.

SpEL in @SendTo

The default reply address (@SendTo) for a @RabbitListener can now be a SpEL expression.

Multiple Queue Names Via Properties

It is now possible to use a combination of SpEL and property placeholders to specify multiple queues for a listener.

RabbitTemplate Changes

reply-address

The reply-address attribute has been added to the <rabbit-template> component as an alternative reply-queue.
See Section 3.1.8, “Request/Reply Messaging” for more information.
(Also available in 1.4.4 as a setter on the RabbitTemplate).

Blocking Receive Methods

Mandatory with SendAndReceive Methods

When the mandatory flag is set when using sendAndReceive and convertSendAndReceive methods, the calling thread
will throw an AmqpMessageReturnedException if the request message can’t be deliverted.
See the section called “Reply Timeout” for more information.

Improper Reply Listener Configuration

The framework will attempt to verify proper configuration of a reply listener container when using a named
reply queue.

Listener Container Bean Names (XML)

Important

The id attribute on the <listener-container/> element has been removed.
Starting with this release, the id on the <listener/> child element is used alone to name the listener container
bean created for each listener element.

Normal Spring bean name overrides are applied; if a later <listener/> is parsed with the same id as an existing
bean, the new definition will override the existing one.
Previously, bean names were composed from the ids of the <listener-container/> and <listener/> elements.

When migrating to this release, if you have id s on your <listener-container/> elements, remove them and set the
id on the child <listener/> element instead.

However, to support starting/stopping containers as a group, a new group attribute has been added.
When this attribute is defined, the containers created by this element are added to a bean with this name, of type
Collection<SimpleMessageListenerContainer.
You can iterate over this group to start/stop containers.

Class-Level @RabbitListener

The @RabbitListener annotation can now be applied at the class level.
Together with the new @RabbitHandler method annotation, this allows the handler method to be selected based on payload
type. See the section called “Multi-Method Listeners” for more information.

Application Events

Consumer Tag Configuration

Previously, the consumer tags for asynchronous consumers were generated by the broker.
With this release, it is now possible to supply a naming strategy to the listener container.
See the section called “Consumer Tags”.

MessageListenerAdapter

The MessageListenerAdapter now supports a map of queue names (or consumer tags) to method names, to determine
which delegate method to call based on the queue the message was received from.

LocalizedQueueConnectionFactory

A new connection factory that connects to the node in a cluster where a mirrored queue actually resides.

RabbitMessagingTemplate

A new RabbitMessagingTemplate is provided to allow users to interact with RabbitMQ using spring-messagingMessage`s.
It uses the `RabbitTemplate internally which can be configured as normal.
Spring Framework 4.1 is required for this feature.
See the section called “Messaging integration” for more information.

Log Appender

The Logback org.springframework.amqp.rabbit.logback.AmqpAppender has been introduced.
It provides similar options like org.springframework.amqp.rabbit.log4j.AmqpAppender.
For more info see JavaDocs of these classes.

The Log4j AmqpAppender now supports the deliveryMode property (PERSISTENT or NON_PERSISTENT, default: PERSISTENT).
Previously, all log4j messages were PERSISTENT.

The appender also supports modification of the Message before sending - allowing, for example, the addition of custom headers.
Subclasses should override the postProcessMessageBeforeSend().

Listener Queues

The listener container now, by default, redeclares any missing queues during startup.
A new auto-declare attribute has been added to the <rabbit:listener-container> to prevent these redeclarations.
See the section called “auto-delete Queues”.

RabbitTemplate: mandatory and connectionFactorySelector Expressions

The mandatoryExpression and sendConnectionFactorySelectorExpression and receiveConnectionFactorySelectorExpression SpEL Expression`s properties have been added to the `RabbitTemplate.
The mandatoryExpression is used to evaluate a mandatory boolean value against each request message, when a ReturnCallback is in use.
See the section called “Publisher Confirms and Returns”.
The sendConnectionFactorySelectorExpression and receiveConnectionFactorySelectorExpression are used when an AbstractRoutingConnectionFactory is provided, to determine the lookupKey for the target ConnectionFactory at runtime on each AMQP protocol interaction operation.
See the section called “Routing Connection Factory”.

RabbitMQ 3.4 Compatibility

ContentTypeDelegatingMessageConverter

The ContentTypeDelegatingMessageConverter has been introduced to select the MessageConverter to use, based on the contentType property in the MessageProperties.
See Section 3.1.6, “Message Converters” for more information.

2.2.3 Changes in 1.3 Since 1.2

Listener Concurrency

The listener container now supports dynamic scaling of the number of consumers based on workload, or the concurrency can be programmatically changed without stopping the container.
See Section 3.1.14, “Listener Concurrency”.

Listener Queues

The listener container now permits the queue(s) on which it is listening to be modified at runtime.
Also, the container will now start if at least one of its configured queues is available for use.
See Section 3.1.16, “Listener Container Queues”

Rabbit Admin

Direct Exchange Binding

Previously, omitting the key attribute from a binding element of a direct-exchange configuration caused the queue or exchange to be bound with an empty string as the routing key.
Now it is bound with the the name of the provided Queue or Exchange.
Users wishing to bind with an empty string routing key need to specify key="".

AMQP Template

The AmqpTemplate now provides several synchronous receiveAndReply methods.
These are implemented by the RabbitTemplate.
For more information see Section 3.1.5, “Receiving messages”.

Binding Arguments

The <exchange>'s <binding> now supports parsing of the <binding-arguments> sub-element.
The <headers-exchange>'s <binding> now can be configured with a key/value attribute pair (to match on a single header) or with a <binding-arguments> sub-element, allowing matching on multiple headers; these options are mutually exclusive.
See the section called “Introduction”.

Default Error Handler (Since 1.3.2)

A default ConditionalRejectingErrorHandler has been added to the listener container.
This error handler detects message conversion problems (which are fatal) and instructs the container to reject the message to prevent the broker from continually redelivering the unconvertible message.
See Section 3.1.11, “Exception Handling”.

Listener Container 'missingQueuesFatal` Property (Since 1.3.5)

2.2.4 Changes to 1.2 Since 1.1

RabbitMQ Version

Spring AMQP now using RabbitMQ 3.1.x by default (but retains compatibility with earlier versions).
Certain deprecations have been added for features no longer supported by RabbitMQ 3.1.x - federated exchanges and the immediate property on the RabbitTemplate.

Rabbit Admin

The RabbitAdmin now provides an option to allow exchange, queue, and binding declarations to continue when a declaration fails.
Previously, all declarations stopped on a failure.
By setting ignore-declaration-exceptions, such exceptions are logged (WARN), but further declarations continue.
An example where this might be useful is when a queue declaration fails because of a slightly different ttl setting would normally stop other declarations from proceeding.

The RabbitAdmin now provides an additional method getQueueProperties().
This can be used to determine if a queue exists on the broker (returns null for a non-existent queue).
In addition, the current number of messages in the queue, as well as the current number of consumers is returned.

Rabbit Template

Previously, when using the ...sendAndReceive() methods were used with a fixed reply queue, two custom headers were used for correlation data and to retain/restore reply queue information.
With this release, the standard message property correlationId is used by default, although the user can specifiy a custom property to use instead.
In addition, nested replyTo information is now retained internally in the template, instead of using a custom header.

The immediate property is deprecated; users must not set this property when using RabbitMQ 3.0.x or greater.

JSON Message Converters

A Jackson 2.x MessageConverter is now provided, along with the existing converter that uses Jackson 1.x.

Automatic Declaration of Queues, etc

Previously, when declaring queues, exchanges and bindings, it was not possible to define which connection factory was used for the declarations, each RabbitAdmin would declare all components using its connection.

AMQP Remoting

Requested Heart Beats

Several users have asked for the underlying client connection factory’s requestedHeartBeats property to be exposed on the Spring AMQP CachingConnectionFactory.
This is now available; previously, it was necessary to configure the AMQP client factory as a separate bean and provide a reference to it in the CachingConnectionFactory.

2.2.5 Changes to 1.1 Since 1.0

General

Spring-AMQP is now built using gradle.

Adds support for publisher confirms and returns.

Adds support for HA queues, and broker failover.

Adds support for Dead Letter Exchanges/Dead Letter Queues.

AMQP Log4j Appender

Adds an option to support adding a message id to logged messages.

Adds an option to allow the specification of a Charset name to be used when converting String`s to `byte[].