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 (https://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>1.7.13.BUILD-SNAPSHOT</version>
</dependency>

And for gradle:

compile 'org.springframework.amqp:spring-rabbit:1.7.13.BUILD-SNAPSHOT'

Compatibility

While the default Spring Framework version dependency is 4.3.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.

The minimum amqp-client java client library version is 4.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
           https://www.springframework.org/schema/rabbit/spring-rabbit.xsd
           http://www.springframework.org/schema/beans
           https://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 1.7 Since 1.6

AMQP Client library

Spring AMQP now uses the new 4.0.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

The 4.0.x 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.

Log4j2 upgrade

The minimum Log4j2 version (for the AmqpAppender) is now 2.7. The framework is no longer compatible with previous versions. See Section 3.2, “Logging Subsystem AMQP Appenders” for more information.

Logback Appender

This appender no longer captures caller data (method, line number) by default; it can be re-enabled by setting the includeCallerData configuration option. See Section 3.2, “Logging Subsystem AMQP Appenders” for information about the available log appenders.

Spring Retry upgrade

The minimum Spring Retry version is now 1.2. The framework is no longer compatible with previous versions.

Shutdown Behavior

You can now set forceCloseChannel to true so that, if the container threads do not respond to a shutdown within shutdownTimeout, the channel(s) will be forced closed, causing any unacked messages to be requeued. See Section 3.1.15, “Message Listener Container Configuration” for more information.

FasterXML Jackson upgrade

The minimum Jackson version is now 2.8. The framework is no longer compatible with previous versions.

JUnit @Rules

Rules that have up until now been used internally by the framework have now been made available in a separate jar spring-rabbit-junit. See Section 3.4.4, “JUnit @Rules” for more information.

Container Conditional Rollback

When using an external transaction manager (e.g. JDBC), rule-based rollback is now supported when providing the container with a transaction attribute. It is also now more flexible when using a transaction advice.

Connection Naming Strategy

A new ConnectionNameStrategy is now provided to populate the application-specific identification of the target RabbitMQ connection from the AbstractConnectionFactory. See Section 3.1.2, “Connection and Resource Management” for more information.

Listener Container Changes

Transaction Rollback behavior

Message requeue on transaction rollback can now be configured to be consistent, regardless of whether or not a transaction manager is configured. See the section called “A note on Rollback of Received Messages” for more information.

Connection Factory Bean Changes

The RabbitConnectionFactoryBean now provides an enabaleHostnameVerification property; set it to true to enable host name verification. Also setHostnameVerifier is provided for when using Java 6; see the connection factory javadocs for more information. Host name verification requires overriding the amqp-client to 4.8.0 or later.

2.2.2 Earlier Releases

See Section A.2, “Previous Releases” for changes in previous versions.