Spring/spring-amqp
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add Javadocs for RabbitTemplate

Browse Source
This commit is contained in:
Dave Syer
2011-08-19 11:49:50 -07:00
parent a4995d889d
commit 6752d6f806
2 changed files with 273 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
spring-amqp-core/src/main/java/org/springframework/amqp/core/AmqpTemplate.java
View File

@@ -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;
}

75
spring-rabbit/src/main/java/org/springframework/amqp/rabbit/core/RabbitTemplate.java
View File

@@ -42,7 +42,33 @@ import com.rabbitmq.client.Envelope;
import com.rabbitmq.client.GetResponse;
/**
* Helper class that simplifies synchronous RabbitMQ access code.
* <p>
* Helper class that simplifies synchronous RabbitMQ access (sending and receiving messages).
* </p>
*
* <p>
* 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 <code>channelTransacted=true</code> as well).
* </p>
*
* <p>
* 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.
* </p>
*
* <p>
* 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 <b>and</b> 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.
* </p>
*
* @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 <code>""</code>
* 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.
* <p>
* 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;