This guide walks you through the process of setting up a RabbitMQ AMQP server that publishes and subscribes to messages.
What you’ll build
You’ll build an application that publishes a message using Spring AMQP’s RabbitTemplate
and subscribes to the message on a POJO using MessageListenerAdapter
.
What you’ll need
-
About 15 minutes
-
A favorite text editor or IDE
-
JDK 1.8 or later
-
You can also import the code straight into your IDE:
-
-
RabbitMQ server (installation instructions below)
-
How to complete this guide
Like most Spring Getting Started guides, you can start from scratch and complete each step, or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.
To start from scratch, move on to Build with Gradle.
To skip the basics, do the following:
-
Download and unzip the source repository for this guide, or clone it using Git:
git clone https://github.com/spring-guides/gs-messaging-rabbitmq.git
-
cd into
gs-messaging-rabbitmq/initial
-
Jump ahead to Create a RabbitMQ message receiver.
When you’re finished, you can check your results against the code in gs-messaging-rabbitmq/complete
.
Build with Gradle
Build with Maven
Build with your IDE
Set up RabbitMQ broker
Before you can build your messaging application, you need to set up the server that will handle receiving and sending messages.
RabbitMQ is an AMQP server. The server is freely available at http://www.rabbitmq.com/download.html. You can download it manually, or if you are using a Mac with homebrew:
brew install rabbitmq
Unpack the server and launch it with default settings.
rabbitmq-server
You should see something like this:
RabbitMQ 3.1.3. Copyright (C) 2007-2013 VMware, Inc. ## ## Licensed under the MPL. See http://www.rabbitmq.com/ ## ## ########## Logs: /usr/local/var/log/rabbitmq/rabbit@localhost.log ###### ## /usr/local/var/log/rabbitmq/rabbit@localhost-sasl.log ########## Starting broker... completed with 6 plugins.
You can also use Docker Compose to quickly launch a RabbitMQ server if you have docker running locally. There is a docker-compose.yml
in the root of the "complete" project in Github. It is very simple:
docker-compose.yml
rabbitmq:
image: rabbitmq:management
ports:
- "5672:5672"
- "15672:15672"
With this file in the current directory you can run docker-compose up
to get RabbitMQ running in a container.
Create a RabbitMQ message receiver
With any messaging-based application, you need to create a receiver that will respond to published messages.
src/main/java/hello/Receiver.java
package hello;
import java.util.concurrent.CountDownLatch;
import org.springframework.stereotype.Component;
@Component
public class Receiver {
private CountDownLatch latch = new CountDownLatch(1);
public void receiveMessage(String message) {
System.out.println("Received <" + message + ">");
latch.countDown();
}
public CountDownLatch getLatch() {
return latch;
}
}
The Receiver
is a simple POJO that defines a method for receiving messages. When you register it to receive messages, you can name it anything you want.
For convenience, this POJO also has a CountDownLatch . This allows it to signal that the message is received. This is something you are not likely to implement in a production application. |
Register the listener and send a message
Spring AMQP’s RabbitTemplate
provides everything you need to send and receive messages with RabbitMQ. Specifically, you need to configure:
-
A message listener container
-
Declare the queue, the exchange, and the binding between them
-
A component to send some messages to test the listener
Spring Boot automatically creates a connection factory and a RabbitTemplate, reducing the amount of code you have to write. |
You’ll use RabbitTemplate
to send messages, and you will register a Receiver
with the message listener container to receive messages. The connection factory drives both, allowing them to connect to the RabbitMQ server.
src/main/java/hello/Application.java
package hello;
import org.springframework.amqp.core.Binding;
import org.springframework.amqp.core.BindingBuilder;
import org.springframework.amqp.core.Queue;
import org.springframework.amqp.core.TopicExchange;
import org.springframework.amqp.rabbit.connection.ConnectionFactory;
import org.springframework.amqp.rabbit.listener.SimpleMessageListenerContainer;
import org.springframework.amqp.rabbit.listener.adapter.MessageListenerAdapter;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class Application {
final static String queueName = "spring-boot";
@Bean
Queue queue() {
return new Queue(queueName, false);
}
@Bean
TopicExchange exchange() {
return new TopicExchange("spring-boot-exchange");
}
@Bean
Binding binding(Queue queue, TopicExchange exchange) {
return BindingBuilder.bind(queue).to(exchange).with(queueName);
}
@Bean
SimpleMessageListenerContainer container(ConnectionFactory connectionFactory,
MessageListenerAdapter listenerAdapter) {
SimpleMessageListenerContainer container = new SimpleMessageListenerContainer();
container.setConnectionFactory(connectionFactory);
container.setQueueNames(queueName);
container.setMessageListener(listenerAdapter);
return container;
}
@Bean
MessageListenerAdapter listenerAdapter(Receiver receiver) {
return new MessageListenerAdapter(receiver, "receiveMessage");
}
public static void main(String[] args) throws InterruptedException {
SpringApplication.run(Application.class, args);
}
}
@SpringBootApplication
is a convenience annotation that adds all of the following:
-
@Configuration
tags the class as a source of bean definitions for the application context. -
@EnableAutoConfiguration
tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings. -
Normally you would add
@EnableWebMvc
for a Spring MVC app, but Spring Boot adds it automatically when it sees spring-webmvc on the classpath. This flags the application as a web application and activates key behaviors such as setting up aDispatcherServlet
. -
@ComponentScan
tells Spring to look for other components, configurations, and services in thehello
package, allowing it to find the controllers.
The main()
method uses Spring Boot’s SpringApplication.run()
method to launch an application. Did you notice that there wasn’t a single line of XML? No web.xml file either. This web application is 100% pure Java and you didn’t have to deal with configuring any plumbing or infrastructure.
The bean defined in the listenerAdapter()
method is registered as a message listener in the container defined in container()
. It will listen for messages on the "spring-boot" queue. Because the Receiver
class is a POJO, it needs to be wrapped in the MessageListenerAdapter
, where you specify it to invoke receiveMessage
.
JMS queues and AMQP queues have different semantics. For example, JMS sends queued messages to only one consumer. While AMQP queues do the same thing, AMQP producers don’t send messages directly to queues. Instead, a message is sent to an exchange, which can go to a single queue, or fanout to multiple queues, emulating the concept of JMS topics. For more, see Understanding AMQP. |
The message listener container and receiver beans are all you need to listen for messages. To send a message, you also need a Rabbit template.
The queue()
method creates an AMQP queue. The exchange()
method creates a topic exchange. The binding()
method binds these two together, defining the behavior that occurs when RabbitTemplate publishes to an exchange.
Spring AMQP requires that the Queue , the TopicExchange , and the Binding be declared as top level Spring beans in order to be set up properly. |
Send a Test Message
Test messages are sent by a CommandLineRunner
, which also waits for the latch in the receiver and closes the application context:
src/main/java/hello/Runner.java
package hello;
import java.util.concurrent.TimeUnit;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.stereotype.Component;
@Component
public class Runner implements CommandLineRunner {
private final RabbitTemplate rabbitTemplate;
private final Receiver receiver;
private final ConfigurableApplicationContext context;
public Runner(Receiver receiver, RabbitTemplate rabbitTemplate,
ConfigurableApplicationContext context) {
this.receiver = receiver;
this.rabbitTemplate = rabbitTemplate;
this.context = context;
}
@Override
public void run(String... args) throws Exception {
System.out.println("Sending message...");
rabbitTemplate.convertAndSend(Application.queueName, "Hello from RabbitMQ!");
receiver.getLatch().await(10000, TimeUnit.MILLISECONDS);
context.close();
}
}
The runner can be mocked out in tests, so that the receiver can be tested in isolation.
Run the Application
The main()
method starts that process by creating a Spring application context. This starts the message listener container, which will start listening for messages. There is a Runner
bean which is then automatically executed: it retrieves the RabbitTemplate
from the application context and sends a "Hello from RabbitMQ!" message on the "spring-boot" queue. Finally, it closes the Spring application context and the application ends.
Build an executable JAR
You can run the application from the command line with Gradle or Maven. Or you can build a single executable JAR file that contains all the necessary dependencies, classes, and resources, and run that. This makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.
If you are using Gradle, you can run the application using ./gradlew bootRun
. Or you can build the JAR file using ./gradlew build
. Then you can run the JAR file:
If you are using Maven, you can run the application using ./mvnw spring-boot:run
. Or you can build the JAR file with ./mvnw clean package
. Then you can run the JAR file:
The procedure above will create a runnable JAR. You can also opt to build a classic WAR file instead. |
You should see the following output:
Sending message... Received <Hello from RabbitMQ!>
Summary
Congratulations! You’ve just developed a simple publish-and-subscribe application with Spring and RabbitMQ. There’s more you can do with Spring and RabbitMQ than what is covered here, but this should provide a good start.
Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.
All guides are released with an ASLv2 license for the code, and an Attribution, NoDerivatives creative commons license for the writing. |