From 0ce7be441360daf86c86bc62f3416f613d0982ee Mon Sep 17 00:00:00 2001 From: Lucas Saldanha Date: Tue, 7 Jul 2015 04:39:05 -0300 Subject: [PATCH 1/2] Add AMQP section to the documetation Closes gh-3348 --- .../main/asciidoc/spring-boot-features.adoc | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 0314662a82..8e3e403ffa 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -2934,6 +2934,140 @@ more details. +[[boot-features-amqp]] +=== AMQP +The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol for +message-oriented middleware. The Spring AMQP project applies core Spring concepts to the development of +AMQP-based messaging solutions. + +[[boot-features-rabbitmq]] +==== RabbitMQ support +RabbitMQ is a lightweight, reliable, scalable and portable message broker based on the AMQP protocol. +Spring uses RabbitMQ to communicate using the AMQP protocol. + +RabbitMQ configuration is controlled by external configuration properties in +`+spring.rabbitmq.*+`. For example, you might declare the following section in +`application.properties`: + +[source,properties,indent=0] +---- + spring.rabbitmq.host=localhost + spring.rabbitmq.port=5672 + spring.rabbitmq.username=guest + spring.rabbitmq.password=guest +---- + +See +{sc-spring-boot-autoconfigure}/amqp/RabbitProperties.{sc-ext}[`RabbitProperties`] +for more of the supported options. + +TIP: Check http://spring.io/blog/2010/06/14/understanding-amqp-the-protocol-used-by-rabbitmq/[Understanding AMQP, the protocol used by RabbitMQ] +for more details. + +[[boot-features-using-amqp-template]] +[[boot-features-using-amqp-sending]] +==== Sending a message +Spring's `AmqpTemplate` and `AmqpAdmin` are auto-configured and you can autowire them directly into your own +beans: + +[source,java,indent=0] +---- + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.amqp.core.AmqpAdmin; + import org.springframework.amqp.core.AmqpTemplate; + import org.springframework.stereotype.Component; + + @Component + public class MyBean { + + private final AmqpAdmin amqpAdmin; + + private final AmqpTemplate amqpTemplate; + + @Autowired + public MyBean(AmqpAdmin amqpAdmin, AmqpTemplate amqpTemplate) { + this.adminTemplate = adminTemplate; + this.amqpTemplate = amqpTemplate; + } + + // ... + + } +---- + +To send a message you should declare a queue using `AmqpAdmin` and then use `AmqpTemplate` to send +the message to the declared queue. + +[source,java,indent=0] +---- + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.amqp.core.AmqpAdmin; + import org.springframework.amqp.core.AmqpTemplate; + import org.springframework.stereotype.Component; + + @Component + public class MyBean { + // ... + + @PostConstruct + public void setUpQueue() { + this.amqpAdmin.declareQueue(new Queue("foo")); + } + + public void send() { + this.rabbitTemplate.convertAndSend("foo", "hello"); + } + + } +---- + + +[[boot-features-using-amqp-receiving]] +==== Receiving a message +Spring's `ConnectionFactory` is auto-configured and you can autowire it directly into your own +beans. + +To receive a message from a queue you should create a `SimpleMessageListenerContainer` +using the configured `ConnectionFactory`. The `SimpleMessageListenerContainer` is +responsible for handling incoming messages through it's `MessageListenerAdapter`. + +[source,java,indent=0] +---- + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.amqp.rabbit.connection.ConnectionFactory; + import org.springframework.amqp.rabbit.listener.SimpleMessageListenerContainer; + import org.springframework.amqp.rabbit.listener.adapter.MessageListenerAdapter; + + @SpringBootApplication + public class AmqpDemoApplication { + + @Autowired + private ConnectionFactory connectionFactory; + + @Bean + public SimpleMessageListenerContainer container() { + SimpleMessageListenerContainer container = new SimpleMessageListenerContainer( + this.connectionFactory); + MessageListenerAdapter adapter = new MessageListenerAdapter(new Object() { + public void handleMessage(String msg) { + System.out.println(msg); + } + }); + container.setMessageListener(adapter); + container.setQueueNames("foo"); + return container; + } + + // ... + + } +---- + +In the code above the `SimpleMessageListenerContainer` was configured to receive messages from the declared "foo" queue. +When a message is sent to "foo" queue it will be delivered to the handleMessage(String msg) method. + + + [[boot-features-email]] == Sending email The Spring Framework provides an easy abstraction for sending email using the From 4602558a739bcc561e482719c7fec0b7f52a33a5 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Tue, 7 Jul 2015 17:14:20 +0200 Subject: [PATCH 2/2] Polish AMQP doc Closes gh-3431 --- spring-boot-docs/src/main/asciidoc/index.adoc | 1 + .../main/asciidoc/spring-boot-features.adoc | 95 ++++++------------- 2 files changed, 28 insertions(+), 68 deletions(-) diff --git a/spring-boot-docs/src/main/asciidoc/index.adoc b/spring-boot-docs/src/main/asciidoc/index.adoc index d805cba5af..2cf8031ecc 100644 --- a/spring-boot-docs/src/main/asciidoc/index.adoc +++ b/spring-boot-docs/src/main/asciidoc/index.adoc @@ -34,6 +34,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson; :spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/htmlsingle :spring-security-reference: http://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle :spring-javadoc: http://docs.spring.io/spring/docs/{spring-docs-version}/javadoc-api/org/springframework +:spring-amqp-javadoc: http://docs.spring.io/spring-amqp/docs/current/api/org/springframework/amqp :spring-data-javadoc: http://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa :spring-data-commons-javadoc: http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data :spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 8e3e403ffa..9438a3d533 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -2867,7 +2867,6 @@ locate a JMS `ConnectionFactory` using JNDI. By default the locations `java:/Jms -[[boot-features-using-jms-template]] [[boot-features-using-jms-sending]] ==== Sending a message Spring's `JmsTemplate` is auto-configured and you can autowire it directly into your own @@ -2936,14 +2935,14 @@ more details. [[boot-features-amqp]] === AMQP -The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol for -message-oriented middleware. The Spring AMQP project applies core Spring concepts to the development of -AMQP-based messaging solutions. +The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol +for message-oriented middleware. The Spring AMQP project applies core Spring concepts to +the development of AMQP-based messaging solutions. [[boot-features-rabbitmq]] ==== RabbitMQ support -RabbitMQ is a lightweight, reliable, scalable and portable message broker based on the AMQP protocol. -Spring uses RabbitMQ to communicate using the AMQP protocol. +RabbitMQ is a lightweight, reliable, scalable and portable message broker based on the +AMQP protocol. Spring uses `RabbitMQ` to communicate using the AMQP protocol. RabbitMQ configuration is controlled by external configuration properties in `+spring.rabbitmq.*+`. For example, you might declare the following section in @@ -2953,8 +2952,8 @@ RabbitMQ configuration is controlled by external configuration properties in ---- spring.rabbitmq.host=localhost spring.rabbitmq.port=5672 - spring.rabbitmq.username=guest - spring.rabbitmq.password=guest + spring.rabbitmq.username=admin + spring.rabbitmq.password=secret ---- See @@ -2964,24 +2963,22 @@ for more of the supported options. TIP: Check http://spring.io/blog/2010/06/14/understanding-amqp-the-protocol-used-by-rabbitmq/[Understanding AMQP, the protocol used by RabbitMQ] for more details. -[[boot-features-using-amqp-template]] [[boot-features-using-amqp-sending]] ==== Sending a message -Spring's `AmqpTemplate` and `AmqpAdmin` are auto-configured and you can autowire them directly into your own -beans: +Spring's `AmqpTemplate` and `AmqpAdmin` are auto-configured and you can autowire them +directly into your own beans: [source,java,indent=0] ---- - import org.springframework.beans.factory.annotation.Autowired; import org.springframework.amqp.core.AmqpAdmin; import org.springframework.amqp.core.AmqpTemplate; + import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; @Component public class MyBean { private final AmqpAdmin amqpAdmin; - private final AmqpTemplate amqpTemplate; @Autowired @@ -2995,76 +2992,38 @@ beans: } ---- -To send a message you should declare a queue using `AmqpAdmin` and then use `AmqpTemplate` to send -the message to the declared queue. +NOTE: {spring-amqp-javadoc}/rabbit/core/RabbitMessagingTemplate.{dc-ext}[`RabbitMessagingTemplate`] +can be injected in a similar manner. -[source,java,indent=0] ----- - import org.springframework.beans.factory.annotation.Autowired; - import org.springframework.amqp.core.AmqpAdmin; - import org.springframework.amqp.core.AmqpTemplate; - import org.springframework.stereotype.Component; - - @Component - public class MyBean { - // ... - - @PostConstruct - public void setUpQueue() { - this.amqpAdmin.declareQueue(new Queue("foo")); - } - - public void send() { - this.rabbitTemplate.convertAndSend("foo", "hello"); - } - - } ----- +Any `org.springframework.amqp.core.Queue` that is defined as a bean will be automatically +used to declare a corresponding queue on the RabbitMQ instance if necessary. [[boot-features-using-amqp-receiving]] ==== Receiving a message -Spring's `ConnectionFactory` is auto-configured and you can autowire it directly into your own -beans. -To receive a message from a queue you should create a `SimpleMessageListenerContainer` -using the configured `ConnectionFactory`. The `SimpleMessageListenerContainer` is -responsible for handling incoming messages through it's `MessageListenerAdapter`. +When the Rabbit infrastructure is present, any bean can be annotated with `@RabbitListener` +to create a listener endpoint. If no `RabbitListenerContainerFactory` has been defined, a +default one is configured automatically. -[source,java,indent=0] ----- - import org.springframework.beans.factory.annotation.Autowired; - import org.springframework.amqp.rabbit.connection.ConnectionFactory; - import org.springframework.amqp.rabbit.listener.SimpleMessageListenerContainer; - import org.springframework.amqp.rabbit.listener.adapter.MessageListenerAdapter; +The following component creates a listener endpoint on the `someQueue` queue: - @SpringBootApplication - public class AmqpDemoApplication { - @Autowired - private ConnectionFactory connectionFactory; +[source,java,indent=0] +---- + @Component + public class MyBean { - @Bean - public SimpleMessageListenerContainer container() { - SimpleMessageListenerContainer container = new SimpleMessageListenerContainer( - this.connectionFactory); - MessageListenerAdapter adapter = new MessageListenerAdapter(new Object() { - public void handleMessage(String msg) { - System.out.println(msg); - } - }); - container.setMessageListener(adapter); - container.setQueueNames("foo"); - return container; + @RabbitListener(queues = "someQueue") + public void processMessage(String content) { + // ... } - // ... - } ---- -In the code above the `SimpleMessageListenerContainer` was configured to receive messages from the declared "foo" queue. -When a message is sent to "foo" queue it will be delivered to the handleMessage(String msg) method. +TIP: Check {spring-amqp-javadoc}/rabbit/annotation/EnableRabbit.{dc-ext}[the Javadoc of `@EnableRabbit`] +for more details.