diff --git a/src/reference/docbook/amqp.xml b/src/reference/docbook/amqp.xml
index c714d89fa8..9dd5e3213c 100644
--- a/src/reference/docbook/amqp.xml
+++ b/src/reference/docbook/amqp.xml
@@ -7,9 +7,9 @@
Introduction
- Spring Integration provides Channel Adapters for receiving and sending
+ Spring Integration provides Channel Adapters for receiving and sending
messages using the Advanced Message Queuing Protocol (AMQP).
-
+
The following adapters are available:
Inbound Channel Adapter
@@ -23,24 +23,24 @@
publish/subscribe Message Channel backed by AMQP Exchanges and Queues.
- In order to provide AMQP support, Spring Integration relies on Spring AMQP
- (http://www.springsource.org/spring-amqp)
- which "applies core Spring concepts to the development of AMQP-based
- messaging solutions". Spring AMQP provides similar semantics as Spring JMS
+ In order to provide AMQP support, Spring Integration relies on Spring AMQP
+ (http://www.springsource.org/spring-amqp)
+ which "applies core Spring concepts to the development of AMQP-based
+ messaging solutions". Spring AMQP provides similar semantics as Spring JMS
(http://.../spring-framework-reference.html#jms).
- Whereas the provided AMQP Channel Adapters are intended for unidirectional
- Messaging (send or receive) only, Spring Integration also provides inbound
- and outbound AMQP Gateways for request/reply operations.
+ Whereas the provided AMQP Channel Adapters are intended for unidirectional
+ Messaging (send or receive) only, Spring Integration also provides inbound
+ and outbound AMQP Gateways for request/reply operations.
- Please familiarize yourself with the reference documentation of
- the Spring AMQP project as well. It provides much more in-depth information
- regarding Spring's integration with AMQP in general and RabbitMQ in
+ Please familiarize yourself with the reference documentation of
+ the Spring AMQP project as well. It provides much more in-depth information
+ regarding Spring's integration with AMQP in general and RabbitMQ in
particular.
- You can find the documentation at:
+ You can find the documentation at:
http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/
@@ -50,7 +50,7 @@
Inbound Channel Adapter
- A configuration sample for an AMQP Inbound Channel Adapter is shown
+ A configuration sample for an AMQP Inbound Channel Adapter is shown
below with all available parameters.
Required.
- Names of the AMQP Queues from which Messages should be
+ Names of the AMQP Queues from which Messages should be
consumed (comma-separated list).
Required.
Acknowledge Mode for the MessageListenerContainer.
Optional (Defaults to AUTO).
-
+
Extra AOP Advice(s) to handle cross cutting behavior associated with this Inbound Channel Adapter.
Optional.
-
+
- Flag to indicate that channels created by this component
- will be transactional. Ff true, tells the framework to use
- a transactional channel and to end all operations (send or
- receive) with a commit or rollback depending on the outcome,
+ Flag to indicate that channels created by this component
+ will be transactional. Ff true, tells the framework to use
+ a transactional channel and to end all operations (send or
+ receive) with a commit or rollback depending on the outcome,
with an exception signalling a rollback.
Optional (Defaults to false).
-
+
- Specify the number of concurrent consumers to create.
- Default is 1. Raising the number of concurrent consumers
- is recommended in order to scale the consumption of
- messages coming in from a queue. However, note that any
- ordering guarantees are lost once multiple consumers are
- registered. In general, stick with 1 consumer for
+ Specify the number of concurrent consumers to create.
+ Default is 1. Raising the number of concurrent consumers
+ is recommended in order to scale the consumption of
+ messages coming in from a queue. However, note that any
+ ordering guarantees are lost once multiple consumers are
+ registered. In general, stick with 1 consumer for
low-volume queues.
Optional.
-
+
Bean reference to the RabbitMQ ConnectionFactory.
Optional (Defaults to 'connectionFactory').
-
+
Message Channel to which error Messages should be sent.
Optional.
-
+
- Shall the listener channel (com.rabbitmq.client.Channel) be
+ Shall the listener channel (com.rabbitmq.client.Channel) be
exposed to a registered ChannelAwareMessageListener.
Optional (Defaults to true).
-
+
HeaderMapper to use when receiving AMQP Messages.
Optional.
By default only standard AMQP properties (e.g. contentType) will be copied to and from
Spring Integration MessageHeaders. Any user-defined headers within the AMQP
- MessageProperties will NOT be copied to or from an AMQP Message unless
+ MessageProperties will NOT be copied to or from an AMQP Message unless
explicitly identified via 'requestHeaderNames' and/or 'replyHeaderNames' properties of this HeaderMapper.
If you need to copy all user-defined headers simply use wild-card character '*'.
-
+
Comma-separated list of names of AMQP Headers to be mapped from the AMQP request into the MessageHeaders.
This can only be provided if the 'header-mapper' reference is not being set directly. The values in
this list can also be simple patterns to be matched against the header names (e.g. "*" or "foo*, bar" or "*foo").
-
+
Comma-separated list of names of MessageHeaders to be mapped into the AMQP Message Properties of the AMQP reply message.
- All standard Headers (e.g., contentType) will be mapped to AMQP Message Properties while user-defined headers will be mapped to 'headers' property
+ All standard Headers (e.g., contentType) will be mapped to AMQP Message Properties while user-defined headers will be mapped to 'headers' property
which itself is a Map.
This can only be provided if the 'header-mapper' reference is not being set directly. The values in
this list can also be simple patterns to be matched against the header names (e.g. "*" or "foo*, bar" or "*foo").
-
+
- Reference to the SimpleMessageListenerContainer
- to use for receiving AMQP Messages. If this attribute is provided,
- then no other attribute related to the listener container
- configuration should be provided. In other words, by
- setting this reference, you must take full responsibility
- of the listener container configuration. The only exception
- is the MessageListener itself. Since that is actually the
- core responsibility of this Channel Adapter implementation,
- the referenced listener container must NOT already have its
+ Reference to the SimpleMessageListenerContainer
+ to use for receiving AMQP Messages. If this attribute is provided,
+ then no other attribute related to the listener container
+ configuration should be provided. In other words, by
+ setting this reference, you must take full responsibility
+ of the listener container configuration. The only exception
+ is the MessageListener itself. Since that is actually the
+ core responsibility of this Channel Adapter implementation,
+ the referenced listener container must NOT already have its
own MessageListener configured.
Optional.
-
+
The MessageConverter to use when receiving AMQP Messages.
Optional.
-
+
The MessagePropertiesConverter to use when receiving AMQP Messages.
Optional.
- Specify the phase in which the underlying SimpleMessageListenerContainer
- should be started and stopped. The startup order proceeds
- from lowest to highest, and the shutdown order is the
- reverse of that. By default this value is Integer.MAX_VALUE
- meaning that this container starts as late as possible and
+ Specify the phase in which the underlying SimpleMessageListenerContainer
+ should be started and stopped. The startup order proceeds
+ from lowest to highest, and the shutdown order is the
+ reverse of that. By default this value is Integer.MAX_VALUE
+ meaning that this container starts as late as possible and
stops as soon as possible.
Optional.
- Tells the AMQP broker how many messages to send to each
- consumer in a single request. Often this can be set quite
- high to improve throughput. It should be greater than or
+ Tells the AMQP broker how many messages to send to each
+ consumer in a single request. Often this can be set quite
+ high to improve throughput. It should be greater than or
equal to the transaction size (see attribute "tx-size").
Optional (Defaults to 1).
Receive timeout in milliseconds.
Optional (Defaults to 1000).
-
+
- Specifies the interval between recovery attempts of the underlying
- SimpleMessageListenerContainer (in
+ Specifies the interval between recovery attempts of the underlying
+ SimpleMessageListenerContainer (in
milliseconds).
Optional (Defaults to 5000).
-
+
- The time to wait for workers in milliseconds after the
- underlying SimpleMessageListenerContainer
- is stopped, and before the AMQP connection is forced closed.
- If any workers are active when the shutdown signal comes
- they will be allowed to finish processing as long as they
- can finish within this timeout. Otherwise the connection is
- closed and messages remain unacked (if the channel is
+ The time to wait for workers in milliseconds after the
+ underlying SimpleMessageListenerContainer
+ is stopped, and before the AMQP connection is forced closed.
+ If any workers are active when the shutdown signal comes
+ they will be allowed to finish processing as long as they
+ can finish within this timeout. Otherwise the connection is
+ closed and messages remain unacked (if the channel is
transactional). Defaults to 5000 milliseconds.
Optional (Defaults to 5000).
- By default, the underlying SimpleMessageListenerContainer
- uses a SimpleAsyncTaskExecutor implementation, that fires
- up a new Thread for each task, executing it asynchronously.
- By default, the number of concurrent threads is unlimited.
-
- NOTE: This implementation does not reuse threads. Consider
+ By default, the underlying SimpleMessageListenerContainer
+ uses a SimpleAsyncTaskExecutor implementation, that fires
+ up a new Thread for each task, executing it asynchronously.
+ By default, the number of concurrent threads is unlimited.
+
+ NOTE: This implementation does not reuse threads. Consider
a thread-pooling TaskExecutor implementation as an alternative.
Optional (Defaults to SimpleAsyncTaskExecutor).
-
+
- By default the underlying SimpleMessageListenerContainer
- creates a new instance of the DefaultTransactionAttribute (takes
- the EJB approach to rolling back on runtime, but not checked
+ By default the underlying SimpleMessageListenerContainer
+ creates a new instance of the DefaultTransactionAttribute (takes
+ the EJB approach to rolling back on runtime, but not checked
exceptions.
Optional (Defaults to DefaultTransactionAttribute).
-
+
- Sets a Bean reference to an external
- PlatformTransactionManager on the
- underlying SimpleMessageListenerContainer. The transaction
- manager works in conjunction with the "channel-transacted"
- attribute.
-
- If there is already a transaction in progress when the
- framework is sending or receiving a message, and the
- channelTransacted flag is true, then the commit or rollback
- of the messaging transaction will be deferred until the
- end of the current transaction. If the channelTransacted
- flag is false, then no transaction semantics apply to the
+ Sets a Bean reference to an external
+ PlatformTransactionManager on the
+ underlying SimpleMessageListenerContainer. The transaction
+ manager works in conjunction with the "channel-transacted"
+ attribute.
+
+ If there is already a transaction in progress when the
+ framework is sending or receiving a message, and the
+ channelTransacted flag is true, then the commit or rollback
+ of the messaging transaction will be deferred until the
+ end of the current transaction. If the channelTransacted
+ flag is false, then no transaction semantics apply to the
messaging operation (it is auto-acked). For further information
- see chapter 1.9 of the Spring AMQP reference guide:
-
+ see chapter 1.9 of the Spring AMQP reference guide:
+
http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/#d0e525
Optional.
- Tells the SimpleMessageListenerContainer
- how many messages to process in a single transaction (if
- the channel is transactional). For best results it should
+ Tells the SimpleMessageListenerContainer
+ how many messages to process in a single transaction (if
+ the channel is transactional). For best results it should
be less than or equal to the set "prefetch-count".
Optional (Defaults to 1).
-
-
+
+
Even though the Spring Integration JMS and AMQP support is very similar,
- important differences exist. The JMS Inbound Channel Adapter is using a
+ important differences exist. The JMS Inbound Channel Adapter is using a
JmsDestinationPollingSource under the covers and expects a configured Poller.
-
- The AMQP Inbound Channel Adapter on the other side uses a
- SimpleMessageListenerContainer and is message
- driven. In that regard it is more similar to the JMS Message
+
+ The AMQP Inbound Channel Adapter on the other side uses a
+ SimpleMessageListenerContainer and is message
+ driven. In that regard it is more similar to the JMS Message
Driven Channel Adapter.
-
+
Outbound Channel Adapter
- A configuration sample for an AMQP Outbound Channel Adapter is shown
+ A configuration sample for an AMQP Outbound Channel Adapter is shown
below with all available parameters.
Optional.
- Message Channel to which Messages should be sent
- in order to have them converted and published to an
+ Message Channel to which Messages should be sent
+ in order to have them converted and published to an
AMQP Exchange.
Required.
@@ -303,13 +303,13 @@ this list can also be simple patterns to be matched against the header names (e.
Optional (Defaults to "amqpTemplate").
- The name of the AMQP Exchange to which Messages
- should be sent. If not provided, Messages will be sent
+ The name of the AMQP Exchange to which Messages
+ should be sent. If not provided, Messages will be sent
to the default, no-name Exchange.
Optional.
- The order for this consumer when multiple
+ The order for this consumer when multiple
consumers are registered thereby enabling load-
balancing and/or failover.
Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE]).
@@ -320,8 +320,8 @@ this list can also be simple patterns to be matched against the header names (e.
Optional.
- The routing-key to use when sending Messages
- evaluated as an expression on the message (e.g.
+ The routing-key to use when sending Messages
+ evaluated as an expression on the message (e.g.
'payload.key'). By default, this will be an empty String.
Optional.
@@ -352,13 +352,13 @@ this list can also be simple patterns to be matched against the header names (e.
amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey.
Optional.
-
-
+
+
-
+
Inbound Gateway
- A configuration sample for an AMQP Inbound Gateway is shown
+ A configuration sample for an AMQP Inbound Gateway is shown
below with all available parameters.
Optional.
- Specify the number of concurrent consumers to
- create. Default is 1. Raising the number of concurrent
- consumers is recommended in order to scale the
- consumption of messages coming in from a queue.
- However, note that any ordering guarantees are lost
- once multiple consumers are registered. In general,
+ Specify the number of concurrent consumers to
+ create. Default is 1. Raising the number of concurrent
+ consumers is recommended in order to scale the
+ consumption of messages coming in from a queue.
+ However, note that any ordering guarantees are lost
+ once multiple consumers are registered. In general,
stick with 1 consumer for low-volume queues.
Optional (Defaults to 1).
@@ -404,13 +404,13 @@ this list can also be simple patterns to be matched against the header names (e.
Message Channel where reply Messages will be expected.
Optional.
-
-
+
+
Outbound Gateway
- A configuration sample for an AMQP Outbound Gateway is shown
+ A configuration sample for an AMQP Outbound Gateway is shown
below with all available parameters.
Optional.
- Message Channel to which Messages should be sent
- in order to have them converted and published to an
+ Message Channel to which Messages should be sent
+ in order to have them converted and published to an
AMQP Exchange.
Required.
@@ -439,30 +439,30 @@ this list can also be simple patterns to be matched against the header names (e.
Optional (Defaults to "amqpTemplate").
- The name of the AMQP Exchange to which Messages should
- be sent. If not provided, Messages will be sent to the
+ The name of the AMQP Exchange to which Messages should
+ be sent. If not provided, Messages will be sent to the
default, no-name Exchange.
Optional.
- The order for this consumer when multiple
+ The order for this consumer when multiple
consumers are registered thereby enabling load-
balancing and/or failover.
Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE]).
- Message Channel to which replies should be sent after
+ Message Channel to which replies should be sent after
being received from an AQMP Queue and converted.
Optional.
- The routing-key to use when sending Messages. By default,
+ The routing-key to use when sending Messages. By default,
this will be an empty String.
Optional.
-
+
- The routing-key to use when sending Messages evealuated
- as an expression on the message (e.g. 'payload.key').
+ The routing-key to use when sending Messages evealuated
+ as an expression on the message (e.g. 'payload.key').
By default, this will be an empty String.
Optional.
@@ -485,7 +485,7 @@ this list can also be simple patterns to be matched against the header names (e.
automatically, including the case where that application might send a request/reply to a third
application using an outbound gateway.
-
+
@@ -515,37 +515,97 @@ this list can also be simple patterns to be matched against the header names (e.
"pollable" option for a publish-subscribe-channel; it must be message-driven.
-
-
+
+ AMQP Message Headers
+
+ The Spring Integration AMPQ Adapters will map standard AMQP properties
+ automatically. These properties will be copied by default to and from
+ Spring Integration
+ MessageHeaders
+ using the
+ DefaultAmqpHeaderMapper.
+
+
+ Of course, you can pass in your own implementation of AMQP specific header
+ mappers, as the adapters have respective properties to support that.
+
+
+ Any user-defined headers within the AMQP
+ MessageProperties
+ will NOT be copied to or from an AMQP Message, unless explicitly specified
+ by the requestHeaderNames and/or
+ replyHeaderNames properties of the
+ HeaderMapper.
+
+
+ When mapping user-defined headers, the values can also contain simple
+ wildcard patterns (e.g. "foo*" or "*foo") to be matched. For example,
+ if you need to copy all user-defined headers simply use the wild-card
+ character '*'.
+
+
+ Class AmqpHeaders
+ identifies the default headers that will be used by the
+ DefaultAmqpHeaderMapper:
+
+
+ amqp_appId
+ amqp_clusterId
+ amqp_contentEncoding
+ amqp_contentLength
+ content-type
+ amqp_correlationId
+ amqp_deliveryMode
+ amqp_deliveryTag
+ amqp_expiration
+ amqp_messageCount
+ amqp_messageId
+ amqp_receivedExchange
+ amqp_receivedRoutingKey
+ amqp_redelivered
+ amqp_replyTo
+ amqp_timestamp
+ amqp_type
+ amqp_userId
+ amqp_springReplyCorrelation
+ amqp_springReplyToStack
+ amqp_publishConfirm
+ amqp_returnReplyCode
+ amqp_returnReplyText
+ amqp_returnExchange
+ amqp_returnRoutingKey
+
+
+
AMQP Samples
- To experiment with the AMQP adapters, check out the samples available in
- the Spring Integration Samples Git repository at:
+ To experiment with the AMQP adapters, check out the samples available in
+ the Spring Integration Samples Git repository at:
https://github.com/SpringSource/spring-integration-samples
-
+
- Currently there is one sample available that demonstrates the basic
+ Currently there is one sample available that demonstrates the basic
functionality of the Spring Integration AMQP Adapter using an Outbound Channel Adapter
- and an Inbound Channel Adapter. As AMQP Broker implementation the sample
+ and an Inbound Channel Adapter. As AMQP Broker implementation the sample
uses RabbitMQ (http://www.rabbitmq.com/).
- In order to run the example you will need a running instance of RabbitMQ.
- A local installation with just the basic defaults will be sufficient.
- For detailed RabbitMQ installation procedures please visit:
+ In order to run the example you will need a running instance of RabbitMQ.
+ A local installation with just the basic defaults will be sufficient.
+ For detailed RabbitMQ installation procedures please visit:
http://www.rabbitmq.com/install.html
- Once the sample application is started, you enter some text on the command prompt
- and a message containing that entered text is dispatched to the AMQP queue.
- In return that message is retrieved via Spring Integration and then printed
- to the console.
+ Once the sample application is started, you enter some text on the command prompt
+ and a message containing that entered text is dispatched to the AMQP queue.
+ In return that message is retrieved via Spring Integration and then printed
+ to the console.
The image belows illustrates the basic set of Spring Integration components