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:

<dependency>
  <groupId>org.springframework.amqp</groupId>
  <artifactId>spring-rabbit</artifactId>
  <version>2.1.1.RELEASE</version>
</dependency>

And for gradle:

compile 'org.springframework.amqp:spring-rabbit:2.1.1.RELEASE'

Compatibility

The minimum Spring Framework version dependency is 5.0.x.

The minimum amqp-client java client library version is 5.0.0.

Very, Very Quick

Using plain, imperative Java to send and receive a message:

ConnectionFactory connectionFactory = new CachingConnectionFactory();
AmqpAdmin admin = new RabbitAdmin(connectionFactory);
admin.declareQueue(new Queue("myqueue"));
AmqpTemplate template = new RabbitTemplate(connectionFactory);
template.convertAndSend("myqueue", "foo");
String foo = (String) template.receiveAndConvert("myqueue");

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:

ApplicationContext context =
    new GenericXmlApplicationContext("classpath:/rabbit-context.xml");
AmqpTemplate template = context.getBean(AmqpTemplate.class);
template.convertAndSend("myqueue", "foo");
String foo = (String) template.receiveAndConvert("myqueue");
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:rabbit="http://www.springframework.org/schema/rabbit"
       xsi:schemaLocation="http://www.springframework.org/schema/rabbit
           http://www.springframework.org/schema/rabbit/spring-rabbit.xsd
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd">

    <rabbit:connection-factory id="connectionFactory"/>

    <rabbit:template id="amqpTemplate" connection-factory="connectionFactory"/>

    <rabbit:admin connection-factory="connectionFactory"/>

    <rabbit:queue name="myqueue"/>

</beans>

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.

With Java Configuration

The same example again with the external configuration in Java:

ApplicationContext context =
    new AnnotationConfigApplicationContext(RabbitConfiguration.class);
AmqpTemplate template = context.getBean(AmqpTemplate.class);
template.convertAndSend("myqueue", "foo");
String foo = (String) template.receiveAndConvert("myqueue");

........

@Configuration
public class RabbitConfiguration {

    @Bean
    public ConnectionFactory connectionFactory() {
        return new CachingConnectionFactory("localhost");
    }

    @Bean
    public AmqpAdmin amqpAdmin() {
        return new RabbitAdmin(connectionFactory());
    }

    @Bean
    public RabbitTemplate rabbitTemplate() {
        return new RabbitTemplate(connectionFactory());
    }

    @Bean
    public Queue myQueue() {
       return new Queue("myqueue");
    }
}

2.2 What’s New

2.2.1 Changes in 2.1 Since 2.0

AMQP Client library

Spring AMQP now uses the new 5.2.x version of the amqp-client library provided by the RabbitMQ team. This client has auto recovery configured by default; see the section called “RabbitMQ Automatic Connection/Topology recovery”.

[Note]Note

As of version 4.0, the client enables automatic recovery by default; while compatible with this feature, Spring AMQP has its own recovery mechanisms and the client recovery feature generally isn’t needed. It is recommended to disable amqp-client automatic recovery, to avoid getting AutoRecoverConnectionNotCurrentlyOpenException s when the broker is available, but the connection has not yet recovered. Starting with version 1.7.1, Spring AMQP disables it unless you explicitly create your own RabbitMQ connection factory and provide it to the CachingConnectionFactory. RabbitMQ ConnectionFactory instances created by the RabbitConnectionFactoryBean will also have the option disabled by default.

Package Changes

Certain classes have moved to different packages; most are internal classes and won’t affect user applications. Two exceptions are ChannelAwareMessageListener and RabbitListenerErrorHandler; these interfaces are now in org.springframework.amqp.rabbit.listener.api.

Publisher Confirms Changes

Channels enabled for publisher confirms are not returned to the cache while there are outstanding confirms. See the section called “Publisher Confirms and Returns” for more information.

Listener Container Factory Improvements

The listener container factories can now be used to create any listener container, not just those for use with @RabbitListener s or the @RabbitListenerEndpointRegistry. See the section called “Using Container Factories” for more information.

ChannelAwareMessageListener now inherits from MessageListener.

Broker Event Listener

A BrokerEventListener is introduced to publish selected broker events as ApplicationEvent s. See Section 3.1.12, “Broker Event Listener” for more information.

RabbitAdmin Changes

The RabbitAdmin will discover beans of type Declarables (which is a container for Declarable - Queue, Exchange, Binding objects) and declare the contained objects on the broker. Users are discouraged from using the old mechanism of declaring <Collection<Queue>> etc and should use Declarables beans instead. By default, the old mechanism is disabled. See the section called “Declaring Collections of Exchanges, Queues, Bindings” for more information.

AnonymousQueue s are now declared with x-queue-master-locator set to client-local by default, to ensure the queues are created on the node the application is connected to. See Section 3.1.11, “Configuring the broker” for more information.

RabbitTemplate Changes

The RabbitTemplate now can be configured with the noLocalReplyConsumer option to control a noLocal flag for reply consumers in the sendAndReceive() operations. See Section 3.1.10, “Request/Reply Messaging” for more information.

CorrelationData for publisher confirms now has a ListenableFuture which can be used to get the acknowledgment instead of using a callback. When returns and confirms are enabled, the correlation data, if provided, is populated with the returned message. See the section called “Publisher Confirms and Returns” for more information.

Message Conversion

A new Jackson2XmlMessageConverter is introduced to support converting messages from/to XML format. See the section called “Jackson2XmlMessageConverter” for more information.

Management REST API

The RabbitManagementTemplate is now deprecated in favor of the direct com.rabbitmq.http.client.Client (or com.rabbitmq.http.client.ReactorNettyClient) usage. See Section 3.1.14, “RabbitMQ REST API” for more information.

@RabbitListener Changes

The listener container factory can now be configured with a RetryTemplate and, optionally, a RecoveryCallback used when sending replies. See the section called “Enable Listener Endpoint Annotations” for more information.

Async @RabbitListener Return

@RabbitListener methods can now return ListenableFuture<?> or Mono<?>. See ??? for more information.

Connection Factory Bean Changes

The RabbitConnectionFactoryBean now calls enableHostnameVerification() by default; to revert to the previous behavior, set the enableHostnameVerification property to false.

Connection Factory Changes

The CachingConnectionFactory now unconditionally disables auto recovery in the underlying RabbitMQ ConnectionFactory, even if a pre-configured instance is provided in a constructor. While steps have been taken to make Spring AMQP compatible with auto recovery, certain corner cases have arisen where issues remain. Spring AMQP has had its own recovery mechanism since 1.0.0 and doesn’t need to use the recovery provided by the client. While it is still possible to enable the feature (using cachingConnectionFactory.getRabbitConnectionFactory() .setAutomaticRecoveryEnabled()) after the CachingConnectionFactory is constructed, it is strongly recommended that you not do so. Use a separate RabbitMQ ConnectionFactory if you need auto recovery connections when using the client factory directly (rather than via Spring AMQP components).

Listener Container Changes

The default ConditionalRejectingErrorHandler will now completely discard messages that cause fatal errors if an x-death header is present. See Section 3.1.15, “Exception Handling” for more information.

Immediate requeue

A new ImmediateRequeueAmqpException is introduced to notify a listener container that the message has to be requeued. To utilize this feature a new ImmediateRequeueMessageRecoverer implementation is added.

See the section called “Message Listeners and the Asynchronous Case” for more information.