From 40207c75cc8752cbeb9d6ff3c1df6307dfda108d Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Wed, 4 May 2011 13:41:10 +0100 Subject: [PATCH] Remove references to MessageCreator in user guide --- .../amqp/core/AmqpTemplate.java | 2 +- .../support/converter/MessageConverter.java | 6 +- src/docbkx/amqp.xml | 96 +++++++++---------- 3 files changed, 52 insertions(+), 52 deletions(-) diff --git a/spring-amqp-core/src/main/java/org/springframework/amqp/core/AmqpTemplate.java b/spring-amqp-core/src/main/java/org/springframework/amqp/core/AmqpTemplate.java index 00790f01..6913ff10 100644 --- a/spring-amqp-core/src/main/java/org/springframework/amqp/core/AmqpTemplate.java +++ b/spring-amqp-core/src/main/java/org/springframework/amqp/core/AmqpTemplate.java @@ -21,7 +21,7 @@ import org.springframework.amqp.AmqpException; /** * Specifies a basic set of AMQP operations. * - * Provides synchronous send an receive methods. The convertAndSend and receiveAndConvert + * Provides synchronous send and receive methods. The {@link #convertAndSend(Object)} and {@link #receiveAndConvert()} * methods allow let you send and receive POJO objects. Implementations are expected to * delegate to an instance of {@link org.springframework.amqp.support.converter.MessageConverter} * to perform conversion to and from AMQP byte[] payload type. diff --git a/spring-amqp-core/src/main/java/org/springframework/amqp/support/converter/MessageConverter.java b/spring-amqp-core/src/main/java/org/springframework/amqp/support/converter/MessageConverter.java index 978b8c6f..521d27fd 100644 --- a/spring-amqp-core/src/main/java/org/springframework/amqp/support/converter/MessageConverter.java +++ b/spring-amqp-core/src/main/java/org/springframework/amqp/support/converter/MessageConverter.java @@ -26,15 +26,15 @@ import org.springframework.amqp.core.MessageProperties; public interface MessageConverter { /** - * Convert a Java object to a Rabbit Message. + * Convert a Java object to a Message. * @param object the object to convert - * @return the Rabbit Message + * @return the Message * @throws MessageConversionException in case of conversion failure */ Message toMessage(Object object, MessageProperties messageProperties) throws MessageConversionException; /** - * Convert from a Rabbit GetResponse to a Java object. + * Convert from a Message to a Java object. * @param message the message to convert * @return the converted Java object * @throws MessageConversionException in case of conversion failure diff --git a/src/docbkx/amqp.xml b/src/docbkx/amqp.xml index 4486bd6d..b3d19c71 100644 --- a/src/docbkx/amqp.xml +++ b/src/docbkx/amqp.xml @@ -10,19 +10,21 @@
AMQP Abstractions - The Spring AMQP project consists of a handful of modules, each - represented by a JAR in the distribution. These modules are: spring-amqp, - spring-rabbit, spring-erlang, and spring-rabbit-admin. The 'spring-amqp' - module contains the org.springframework.amqp.core package. Within that + Spring AMQP consists of a handful of modules, each represented by a + JAR in the distribution. These modules are: spring-amqp, spring-rabbit and + spring-erlang. The 'spring-amqp' module contains the + org.springframework.amqp.core package. Within that package, you will find the classes that represent the core AMQP "model". Our intention is to provide generic abstractions that do not rely on any particular AMQP broker implementation or client library. End user code will be more portable across vendor implementations as it can be developed against the abstraction layer only. These abstractions are then used implemented by broker-specific modules, such as 'spring-rabbit'. For the - M1 release there is only a RabbitMQ implementation however the - abstractions have been vetted in .NET using Apache Qpid in addition to - RabbitMQ. + 1.0 release there is only a RabbitMQ implementation however the + abstractions have been validated in .NET using Apache Qpid in addition to + RabbitMQ. Since AMQP operates at the protocol level in principle the + RabbitMQ client can be used with any broker that supports the same + protocol version, but we do not test any other brokers at present. The overview here assumes that you are already familiar with the basics of the AMQP specification already. If you are not, then have a look @@ -308,11 +310,11 @@ Connection connection = connectionFactory.createConnection();]]>When sending a Message, one can use any of the following methods: - +void send(String exchange, String routingKey, Message message) throws AmqpException;]]> We can begin our discussion with the last method listed above since it is actually the most explicit. It allows an AMQP Exchange name to be @@ -321,11 +323,7 @@ void send(String exchange, String routingKey, MessageCreator messageCreator) thr An example of using this method to send a Message might look this this: - + The "exchange" property can be set on the template itself if you plan to use that template instance to send to the same exchange most or @@ -334,23 +332,14 @@ void send(String exchange, String routingKey, MessageCreator messageCreator) thr one: +amqpTemplate.send("quotes.nasdaq.FOO", new Message("12.34".getBytes(), someProperties));]]> If both the "exchange" and "routingKey" properties are set on the template, then the method accepting only the - MessageCreator may be used: + Message may be used: +amqpTemplate.setRoutingKey("quotes.nasdaq.FOO", new Message("12.34".getBytes(), someProperties));]]> A better way of thinking about the exchange and routing key properties is that the explicit method parameters will always override the @@ -371,11 +360,7 @@ amqpTemplate.send(new MessageCreator() { either by providing the method parameter at runtime: +template.send("queue.helloWorld", new Message("Hello World".getBytes(), someProperties));]]> Or, if you prefer to create a template that will be used for publishing primarily or exclusively to a single Queue, the following is @@ -383,22 +368,22 @@ template.send("queue.helloWorld", new MessageCreator() { +template.send(new Message("Hello World".getBytes(), someProperties));]]> + +
Receiving messages Message reception is always a bit more complicated than sending. The - reason is that there are two ways to receive a Message. The simpler option - is to poll for a single Message at a time with a synchronous, blocking + reason is that there are two ways to receive a + Message. The simpler option is to poll for a single + Message at a time with a synchronous, blocking method call. The more complicated yet more common approach is to register - a listener that will receive Messages on-demand, asynchronously. We will - look at an example of each approach in the next two sub-sections. + a listener that will receive Messages on-demand, + asynchronously. We will look at an example of each approach in the next + two sub-sections. Synchronous Consumer @@ -413,9 +398,22 @@ template.send(new MessageCreator() { + + Just like in the case of sending messages, the + AmqpTemplate has some convenience methods for + receiving POJOs instead of Message instances, and + implementations will provide a way to customize the + MessageConverter used to create the + Object returned: + + + + - Asynchronous Consumer For asynchronous Message + Asynchronous ConsumerFor asynchronous Message reception, a dedicated component (not the AmqpTemplate) is involved. That component is a container for a Message consuming callback. We will look at the @@ -518,12 +516,14 @@ public class ExampleAmqpConfiguration { }]]> The relevant Message-sending methods on the - AmqpTemplate are listed below. They are - simpler than the methods we discussed previously because they do not - require the MessageCreator callback. Instead, the MessageConverter is - responsible for "creating" each Message by converting the provided object - to the byte array for the Message body and then adding any provided - MessageProperties. + AmqpTemplate are listed below. They + are simpler than the methods we discussed previously because they + do not require the Message instance. + Instead, the MessageConverter is + responsible for "creating" each Message by + converting the provided object to the byte array for + the Message body and then adding any + provided MessageProperties.