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 04cc7c97..1fd1e3c6 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
@@ -1,17 +1,14 @@
/*
* Copyright 2002-2010 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
*/
package org.springframework.amqp.core;
@@ -22,10 +19,9 @@ import org.springframework.amqp.support.converter.MessageConverter;
/**
* Specifies a basic set of AMQP operations.
*
- * 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 MessageConverter}
- * to perform conversion to and from AMQP byte[] payload type.
+ * 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 MessageConverter} to perform conversion to and from AMQP byte[] payload type.
*
* @author Mark Pollack
* @author Mark Fisher
@@ -34,58 +30,247 @@ public interface AmqpTemplate {
// send methods for messages
+ /**
+ * Send a message to a default exchange with a default routing key.
+ *
+ * @param message a message to send
+ * @throws AmqpException if there is a problem
+ */
void send(Message message) throws AmqpException;
+ /**
+ * Send a message to a default exchange with a specific routing key.
+ *
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @throws AmqpException if there is a problem
+ */
void send(String routingKey, Message message) throws AmqpException;
+ /**
+ * Send a message to a specific exchange with a specific routing key.
+ *
+ * @param exchange the name of the exchange
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @throws AmqpException if there is a problem
+ */
void send(String exchange, String routingKey, Message message) throws AmqpException;
// send methods with conversion
+ /**
+ * Convert a Java object to an Amqp {@link Message} and send it to a default exchange with a default routing key.
+ *
+ * @param message a message to send
+ * @throws AmqpException if there is a problem
+ */
void convertAndSend(Object message) throws AmqpException;
+ /**
+ * Convert a Java object to an Amqp {@link Message} and send it to a default exchange with a specific routing key.
+ *
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @throws AmqpException if there is a problem
+ */
void convertAndSend(String routingKey, Object message) throws AmqpException;
+ /**
+ * Convert a Java object to an Amqp {@link Message} and send it to a specific exchange with a specific routing key.
+ *
+ * @param exchange the name of the exchange
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @throws AmqpException if there is a problem
+ */
void convertAndSend(String exchange, String routingKey, Object message) throws AmqpException;
+ /**
+ * Convert a Java object to an Amqp {@link Message} and send it to a default exchange with a default routing key.
+ *
+ * @param message a message to send
+ * @param messagePostProcessor a processor to apply to the message before it is sent
+ * @throws AmqpException if there is a problem
+ */
void convertAndSend(Object message, MessagePostProcessor messagePostProcessor) throws AmqpException;
- void convertAndSend(String routingKey, Object message, MessagePostProcessor messagePostProcessor) throws AmqpException;
+ /**
+ * Convert a Java object to an Amqp {@link Message} and send it to a specific exchange with a default routing key.
+ *
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @param messagePostProcessor a processor to apply to the message before it is sent
+ * @throws AmqpException if there is a problem
+ */
+ void convertAndSend(String routingKey, Object message, MessagePostProcessor messagePostProcessor)
+ throws AmqpException;
- void convertAndSend(String exchange, String routingKey, Object message, MessagePostProcessor messagePostProcessor) throws AmqpException;
+ /**
+ * Convert a Java object to an Amqp {@link Message} and send it to a specific exchange with a specific routing key.
+ *
+ * @param exchange the name of the exchange
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @param messagePostProcessor a processor to apply to the message before it is sent
+ * @throws AmqpException if there is a problem
+ */
+ void convertAndSend(String exchange, String routingKey, Object message, MessagePostProcessor messagePostProcessor)
+ throws AmqpException;
// receive methods for messages
+ /**
+ * Receive a message if there is one from a default queue. Returns immediately, possibly with a null value.
+ *
+ * @return a message or null if there is none waiting
+ * @throws AmqpException if there is a problem
+ */
Message receive() throws AmqpException;
+ /**
+ * Receive a message if there is one from a specific queue. Returns immediately, possibly with a null value.
+ *
+ * @param queueName the name of the queue to poll
+ * @return a message or null if there is none waiting
+ * @throws AmqpException if there is a problem
+ */
Message receive(String queueName) throws AmqpException;
// receive methods with conversion
+ /**
+ * Receive a message if there is one from a default queue and convert it to a Java object. Returns immediately,
+ * possibly with a null value.
+ *
+ * @return a message or null if there is none waiting
+ * @throws AmqpException if there is a problem
+ */
Object receiveAndConvert() throws AmqpException;
+ /**
+ * Receive a message if there is one from a specific queue and convert it to a Java object. Returns immediately,
+ * possibly with a null value.
+ *
+ * @param queueName the name of the queue to poll
+ * @return a message or null if there is none waiting
+ * @throws AmqpException if there is a problem
+ */
Object receiveAndConvert(String queueName) throws AmqpException;
// send and receive methods for messages
+ /**
+ * Basic RPC pattern. Send a message to a default exchange with a default routing key and attempt to receive a
+ * response. Implementations will normally set the reply-to header to an exclusive queue and wait up for some time
+ * limited by a timeout.
+ *
+ * @param message a message to send
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Message sendAndReceive(Message message) throws AmqpException;
+ /**
+ * Basic RPC pattern. Send a message to a default exchange with a specific routing key and attempt to receive a
+ * response. Implementations will normally set the reply-to header to an exclusive queue and wait up for some time
+ * limited by a timeout.
+ *
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Message sendAndReceive(String routingKey, Message message) throws AmqpException;
+ /**
+ * Basic RPC pattern. Send a message to a specific exchange with a specific routing key and attempt to receive a
+ * response. Implementations will normally set the reply-to header to an exclusive queue and wait up for some time
+ * limited by a timeout.
+ *
+ * @param exchange the name of the exchange
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Message sendAndReceive(String exchange, String routingKey, Message message) throws AmqpException;
// send and receive methods with conversion
+ /**
+ * Basic RPC pattern with conversion. Send a Java object converted to a message to a default exchange with a default
+ * routing key and attempt to receive a response, converting that to a Java object. Implementations will normally
+ * set the reply-to header to an exclusive queue and wait up for some time limited by a timeout.
+ *
+ * @param message a message to send
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Object convertSendAndReceive(Object message) throws AmqpException;
+ /**
+ * Basic RPC pattern with conversion. Send a Java object converted to a message to a default exchange with a
+ * specific routing key and attempt to receive a response, converting that to a Java object. Implementations will
+ * normally set the reply-to header to an exclusive queue and wait up for some time limited by a timeout.
+ *
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Object convertSendAndReceive(String routingKey, Object message) throws AmqpException;
+ /**
+ * Basic RPC pattern with conversion. Send a Java object converted to a message to a specific exchange with a
+ * specific routing key and attempt to receive a response, converting that to a Java object. Implementations will
+ * normally set the reply-to header to an exclusive queue and wait up for some time limited by a timeout.
+ *
+ * @param exchange the name of the exchange
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Object convertSendAndReceive(String exchange, String routingKey, Object message) throws AmqpException;
+ /**
+ * Basic RPC pattern with conversion. Send a Java object converted to a message to a default exchange with a default
+ * routing key and attempt to receive a response, converting that to a Java object. Implementations will normally
+ * set the reply-to header to an exclusive queue and wait up for some time limited by a timeout.
+ *
+ * @param message a message to send
+ * @param messagePostProcessor a processor to apply to the message before it is sent
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Object convertSendAndReceive(Object message, MessagePostProcessor messagePostProcessor) throws AmqpException;
+ /**
+ * Basic RPC pattern with conversion. Send a Java object converted to a message to a default exchange with a
+ * specific routing key and attempt to receive a response, converting that to a Java object. Implementations will
+ * normally set the reply-to header to an exclusive queue and wait up for some time limited by a timeout.
+ *
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @param messagePostProcessor a processor to apply to the message before it is sent
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Object convertSendAndReceive(String routingKey, Object message, MessagePostProcessor messagePostProcessor) throws AmqpException;
+ /**
+ * Basic RPC pattern with conversion. Send a Java object converted to a message to a specific exchange with a
+ * specific routing key and attempt to receive a response, converting that to a Java object. Implementations will
+ * normally set the reply-to header to an exclusive queue and wait up for some time limited by a timeout.
+ *
+ * @param exchange the name of the exchange
+ * @param routingKey the routing key
+ * @param message a message to send
+ * @param messagePostProcessor a processor to apply to the message before it is sent
+ * @return the response if there is one
+ * @throws AmqpException if there is a problem
+ */
Object convertSendAndReceive(String exchange, String routingKey, Object message, MessagePostProcessor messagePostProcessor) throws AmqpException;
}
diff --git a/spring-rabbit/src/main/java/org/springframework/amqp/rabbit/core/RabbitTemplate.java b/spring-rabbit/src/main/java/org/springframework/amqp/rabbit/core/RabbitTemplate.java
index 109a846f..ed5ac442 100644
--- a/spring-rabbit/src/main/java/org/springframework/amqp/rabbit/core/RabbitTemplate.java
+++ b/spring-rabbit/src/main/java/org/springframework/amqp/rabbit/core/RabbitTemplate.java
@@ -42,7 +42,33 @@ import com.rabbitmq.client.Envelope;
import com.rabbitmq.client.GetResponse;
/**
- * Helper class that simplifies synchronous RabbitMQ access code.
+ *
+ * Helper class that simplifies synchronous RabbitMQ access (sending and receiving messages).
+ *
+ *
+ *
+ * The default settings are for non-transactional messaging, which reduces the amount of data exchanged with the broker.
+ * To use a new transaction for every send or receive set the {@link #setChannelTransacted(boolean) channelTransacted}
+ * flag. To extend the transaction over multiple invocations (more efficient), you can use a Spring transaction to
+ * bracket the calls (with channelTransacted=true as well).
+ *
+ *
+ *
+ * The only mandatory property is the {@link #setConnectionFactory(ConnectionFactory) ConnectionFactory}. There are
+ * strategies available for converting messages to and from Java objects (
+ * {@link #setMessageConverter(MessageConverter) MessageConverter}) and for converting message headers (known as message
+ * properties in AMQP, see {@link #setMessagePropertiesConverter(MessagePropertiesConverter) MessagePropertiesConverter}
+ * ). The defaults probably do something sensible for typical use cases, as long as the message content-type is set
+ * appropriately.
+ *
+ *
+ *
+ * The "send" methods all have overloaded versions that allow you to explicitly target an exchange and a routing key, or
+ * you can set default values to be used in all send operations. The plain "receive" methods allow you to explicitly
+ * target a queue to receive from, or you can set a default value for the template that applies to all explicit
+ * receives. The convenience methods for send and receive use the sender defaults if no exchange or routing key
+ * is specified, but they always use a temporary queue for the receive leg, so the default queue is ignored.
+ *
*
* @author Mark Pollack
* @author Mark Fisher
@@ -74,28 +100,57 @@ public class RabbitTemplate extends RabbitAccessor implements RabbitOperations {
private String encoding = DEFAULT_ENCODING;
+ /**
+ * Convenient constructor for use with setter injection. Don't forget to set the connection factory.
+ */
public RabbitTemplate() {
initDefaultStrategies();
}
+ /**
+ * Create a rabbit template with default strategies and settings.
+ *
+ * @param connectionFactory the connection factory to use
+ */
public RabbitTemplate(ConnectionFactory connectionFactory) {
this();
setConnectionFactory(connectionFactory);
afterPropertiesSet();
}
+ /**
+ * Set up the default strategies. Subclasses can override if necessary.
+ */
protected void initDefaultStrategies() {
setMessageConverter(new SimpleMessageConverter());
}
+ /**
+ * The name of the default exchange to use for send operations when none is specified. Defaults to ""
+ * which is the default exchange in the broker (per the AMQP specification).
+ *
+ * @param exchange the exchange name to use for send operations
+ */
public void setExchange(String exchange) {
this.exchange = (exchange != null) ? exchange : DEFAULT_EXCHANGE;
}
+ /**
+ * The value of a default routing key to use for send operations when none is specified. Default is empty which is
+ * not helpful when using the default (or any direct) exchange, but fine if the exchange is a headers exchange for
+ * instance.
+ *
+ * @param exchange the default routing key to use for send operations
+ */
public void setRoutingKey(String routingKey) {
this.routingKey = routingKey;
}
+ /**
+ * The name of the default queue to receive messages from when none is specified explicitly.
+ *
+ * @param queue the default queue name to use for receive
+ */
public void setQueue(String queue) {
this.queue = queue;
}
@@ -112,7 +167,13 @@ public class RabbitTemplate extends RabbitAccessor implements RabbitOperations {
/**
* Specify the timeout in milliseconds to be used when waiting for a reply Message when using one of the
* sendAndReceive methods. The default value is defined as {@link #DEFAULT_REPLY_TIMEOUT}. A negative value
- * indicates an indefinite timeout.
+ * indicates an indefinite timeout. Not used in the plain receive methods because there is no blocking receive
+ * operation defined in the protocol.
+ *
+ * @param replyTimeout the reply timeout in milliseconds
+ *
+ * @see #sendAndReceive(String, String, Message)
+ * @see #convertSendAndReceive(String, String, Object)
*/
public void setReplyTimeout(long replyTimeout) {
this.replyTimeout = replyTimeout;
@@ -123,7 +184,7 @@ public class RabbitTemplate extends RabbitAccessor implements RabbitOperations {
* Object results from receiveAndConvert methods.
*
* The default converter is a SimpleMessageConverter, which is able to handle byte arrays, Strings, and Serializable
- * Objects.
+ * Objects depending on the message content type header.
*
* @see #convertAndSend
* @see #receiveAndConvert
@@ -134,7 +195,10 @@ public class RabbitTemplate extends RabbitAccessor implements RabbitOperations {
}
/**
- * Set the {@link MessagePropertiesConverter} for this template.
+ * Set the {@link MessagePropertiesConverter} for this template. This converter is used to convert between raw byte
+ * content in the message headers and plain Java objects. In particular there are limitations when dealing with very
+ * long string headers, which hopefully are rare in practice, but if you need to use long headers you might need to
+ * inject a special converter here.
*/
public void setMessagePropertiesConverter(MessagePropertiesConverter messagePropertiesConverter) {
Assert.notNull(messagePropertiesConverter, "messagePropertiesConverter must not be null");
@@ -142,7 +206,8 @@ public class RabbitTemplate extends RabbitAccessor implements RabbitOperations {
}
/**
- * Return the message converter for this template.
+ * Return the message converter for this template. Useful for clients that want to take advantage of the converter
+ * in {@link ChannelCallback} implementations.
*/
public MessageConverter getMessageConverter() {
return this.messageConverter;