11e5fe0c0c
Changes to Connection Factory interface (stub). INT-2394 Polishing INT-2394 Map Gateway Correlation Header Map spring_reply_correlation if present. INT-2394 Map ReplyTo Stack Enable the use outbound-gateway in a destination application to which we sent a message using another outbound gateway. The RabbitTemplate now pushed exising correlation data onto a stacked header attribute. INT-2509 Publisher Confirms and Returns Add Publisher Confirm support to the outbound channel adapter. Add returns support to outbound channel adapter and gateway. INT-2509 Polishing PR Review comments. Docs. Fix chain test after rebase.
565 lines
41 KiB
XML
565 lines
41 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="amqp"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>AMQP Support</title>
|
|
|
|
<section id="amqp-introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
Spring Integration provides Channel Adapters for receiving and sending
|
|
messages using the Advanced Message Queuing Protocol (AMQP).
|
|
|
|
The following adapters are available:
|
|
<itemizedlist>
|
|
<listitem>Inbound Channel Adapter</listitem>
|
|
<listitem>Outbound Channel Adapter</listitem>
|
|
<listitem>Inbound Gateway</listitem>
|
|
<listitem>Outbound Gateway</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Spring Integration also provides a point-to-point Message Channel as well as a
|
|
publish/subscribe Message Channel backed by AMQP Exchanges and Queues.
|
|
</para>
|
|
<para>
|
|
In order to provide AMQP support, Spring Integration relies on Spring AMQP
|
|
(<ulink url="http://www.springsource.org/spring-amqp">http://www.springsource.org/spring-amqp</ulink>)
|
|
which "applies core Spring concepts to the development of AMQP-based
|
|
messaging solutions". Spring AMQP provides similar semantics as Spring JMS
|
|
(<ulink url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#jms">http://.../spring-framework-reference.html#jms</ulink>).
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<tip>
|
|
<para>
|
|
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.</para>
|
|
<para>You can find the documentation at:
|
|
<ulink url="http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/">
|
|
http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/</ulink>
|
|
</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Inbound Channel Adapter</title>
|
|
|
|
<para>A configuration sample for an AMQP Inbound Channel Adapter is shown
|
|
below with all available parameters.</para>
|
|
<programlisting language="xml"><![CDATA[<int-amqp:inbound-channel-adapter id="inboundAmqp"]]><co id="amqp-inbound-channel-adapter-xml-01-co" linkends="amqp-inbound-channel-adapter-xml-01" /><![CDATA[
|
|
channel="inboundChannel"]]><co id="amqp-inbound-channel-adapter-xml-02-co" linkends="amqp-inbound-channel-adapter-xml-02" /><![CDATA[
|
|
queue-names="si.test.queue"]]><co id="amqp-inbound-channel-adapter-xml-03-co" linkends="amqp-inbound-channel-adapter-xml-03" /><![CDATA[
|
|
acknowledge-mode="AUTO"]]><co id="amqp-inbound-channel-adapter-xml-04-co" linkends="amqp-inbound-channel-adapter-xml-04" /><![CDATA[
|
|
advice-chain=""]]><co id="amqp-inbound-channel-adapter-xml-05-co" linkends="amqp-inbound-channel-adapter-xml-05" /><![CDATA[
|
|
channel-transacted=""]]><co id="amqp-inbound-channel-adapter-xml-06-co" linkends="amqp-inbound-channel-adapter-xml-06" /><![CDATA[
|
|
concurrent-consumers=""]]><co id="amqp-inbound-channel-adapter-xml-07-co" linkends="amqp-inbound-channel-adapter-xml-07" /><![CDATA[
|
|
connection-factory=""]]><co id="amqp-inbound-channel-adapter-xml-08-co" linkends="amqp-inbound-channel-adapter-xml-08" /><![CDATA[
|
|
error-channel=""]]><co id="amqp-inbound-channel-adapter-xml-09-co" linkends="amqp-inbound-channel-adapter-xml-09" /><![CDATA[
|
|
expose-listener-channel=""]]><co id="amqp-inbound-channel-adapter-xml-10-co" linkends="amqp-inbound-channel-adapter-xml-10" /><![CDATA[
|
|
header-mapper=""]]><co id="amqp-inbound-channel-adapter-xml-11-co" linkends="amqp-inbound-channel-adapter-xml-11" /><![CDATA[
|
|
mapped-request-headers=""]]><co id="amqp-inbound-channel-adapter-xml-12-co" linkends="amqp-inbound-channel-adapter-xml-12" /><![CDATA[
|
|
mapped-reply-headers=""]]><co id="amqp-inbound-channel-adapter-xml-13-co" linkends="amqp-inbound-channel-adapter-xml-13" /><![CDATA[
|
|
listener-container=""]]><co id="amqp-inbound-channel-adapter-xml-14-co" linkends="amqp-inbound-channel-adapter-xml-14" /><![CDATA[
|
|
message-converter=""]]><co id="amqp-inbound-channel-adapter-xml-15-co" linkends="amqp-inbound-channel-adapter-xml-15" /><![CDATA[
|
|
message-properties-converter=""]]><co id="amqp-inbound-channel-adapter-xml-16-co" linkends="amqp-inbound-channel-adapter-xml-16" /><![CDATA[
|
|
phase=""]]><co id="amqp-inbound-channel-adapter-xml-17-co" linkends="amqp-inbound-channel-adapter-xml-17" /><![CDATA[
|
|
prefetch-count=""]]><co id="amqp-inbound-channel-adapter-xml-18-co" linkends="amqp-inbound-channel-adapter-xml-18" /><![CDATA[
|
|
receive-timeout=""]]><co id="amqp-inbound-channel-adapter-xml-19-co" linkends="amqp-inbound-channel-adapter-xml-19" /><![CDATA[
|
|
recovery-interval=""]]><co id="amqp-inbound-channel-adapter-xml-20-co" linkends="amqp-inbound-channel-adapter-xml-20" /><![CDATA[
|
|
shutdown-timeout=""]]><co id="amqp-inbound-channel-adapter-xml-21-co" linkends="amqp-inbound-channel-adapter-xml-21" /><![CDATA[
|
|
task-executor=""]]><co id="amqp-inbound-channel-adapter-xml-22-co" linkends="amqp-inbound-channel-adapter-xml-22" /><![CDATA[
|
|
transaction-attribute=""]]><co id="amqp-inbound-channel-adapter-xml-23-co" linkends="amqp-inbound-channel-adapter-xml-23" /><![CDATA[
|
|
transaction-manager=""]]><co id="amqp-inbound-channel-adapter-xml-24-co" linkends="amqp-inbound-channel-adapter-xml-24" /><![CDATA[
|
|
tx-size=""]]><co id="amqp-inbound-channel-adapter-xml-25-co" linkends="amqp-inbound-channel-adapter-xml-25" /><![CDATA[/>]]>
|
|
</programlisting>
|
|
<para>
|
|
<calloutlist>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-01-co" id="amqp-inbound-channel-adapter-xml-01">
|
|
<para>Unique ID for this adapter.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-02-co" id="amqp-inbound-channel-adapter-xml-02">
|
|
<para>Message Channel to which converted Messages should be sent.
|
|
<emphasis>Required</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-03-co" id="amqp-inbound-channel-adapter-xml-03">
|
|
<para>Names of the AMQP Queues from which Messages should be
|
|
consumed (comma-separated list).
|
|
<emphasis>Required</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-04-co" id="amqp-inbound-channel-adapter-xml-04">
|
|
<para>Acknowledge Mode for the <interface>MessageListenerContainer</interface>.
|
|
<emphasis>Optional (Defaults to AUTO)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-05-co" id="amqp-inbound-channel-adapter-xml-05">
|
|
<para>Extra AOP Advice(s) to handle cross cutting behavior associated with this Inbound Channel Adapter.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-06-co" id="amqp-inbound-channel-adapter-xml-06">
|
|
<para>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.
|
|
<emphasis>Optional (Defaults to false)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-07-co" id="amqp-inbound-channel-adapter-xml-07">
|
|
<para>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.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-08-co" id="amqp-inbound-channel-adapter-xml-08">
|
|
<para>Bean reference to the RabbitMQ ConnectionFactory.
|
|
<emphasis>Optional (Defaults to 'connectionFactory')</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-09-co" id="amqp-inbound-channel-adapter-xml-09">
|
|
<para>Message Channel to which error Messages should be sent.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-10-co" id="amqp-inbound-channel-adapter-xml-10">
|
|
<para>Shall the listener channel (com.rabbitmq.client.Channel) be
|
|
exposed to a registered <interface>ChannelAwareMessageListener</interface>.
|
|
<emphasis>Optional (Defaults to true)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-11-co" id="amqp-inbound-channel-adapter-xml-11">
|
|
<para><classname>HeaderMapper</classname> to use when receiving AMQP Messages.
|
|
<emphasis>Optional</emphasis>.
|
|
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
|
|
explicitly identified via 'requestHeaderNames' and/or 'replyHeaderNames' properties of this <classname>HeaderMapper</classname>.
|
|
If you need to copy all user-defined headers simply use wild-card character '*'.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-12-co" id="amqp-inbound-channel-adapter-xml-12">
|
|
<para>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").</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-13-co" id="amqp-inbound-channel-adapter-xml-13">
|
|
<para>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
|
|
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").</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-14-co" id="amqp-inbound-channel-adapter-xml-14">
|
|
<para>Reference to the <interface>SimpleMessageListenerContainer</interface>
|
|
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.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-15-co" id="amqp-inbound-channel-adapter-xml-15">
|
|
<para>The MessageConverter to use when receiving AMQP Messages.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-16-co" id="amqp-inbound-channel-adapter-xml-16">
|
|
<para>The MessagePropertiesConverter to use when receiving AMQP Messages.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-17-co" id="amqp-inbound-channel-adapter-xml-17">
|
|
<para>Specify the phase in which the underlying <interface>SimpleMessageListenerContainer</interface>
|
|
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.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-18-co" id="amqp-inbound-channel-adapter-xml-18">
|
|
<para>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").
|
|
<emphasis>Optional (Defaults to 1)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-19-co" id="amqp-inbound-channel-adapter-xml-19">
|
|
<para>Receive timeout in milliseconds.
|
|
<emphasis>Optional (Defaults to 1000)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-20-co" id="amqp-inbound-channel-adapter-xml-20">
|
|
<para>Specifies the interval between recovery attempts of the underlying
|
|
<interface>SimpleMessageListenerContainer</interface> (in
|
|
milliseconds).
|
|
<emphasis>Optional (Defaults to 5000)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-21-co" id="amqp-inbound-channel-adapter-xml-21">
|
|
<para>The time to wait for workers in milliseconds after the
|
|
underlying <interface>SimpleMessageListenerContainer</interface>
|
|
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.
|
|
<emphasis>Optional (Defaults to 5000)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-22-co" id="amqp-inbound-channel-adapter-xml-22">
|
|
<para>By default, the underlying <interface>SimpleMessageListenerContainer</interface>
|
|
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.
|
|
<emphasis>Optional (Defaults to SimpleAsyncTaskExecutor)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-23-co" id="amqp-inbound-channel-adapter-xml-23">
|
|
<para>By default the underlying <interface>SimpleMessageListenerContainer</interface>
|
|
creates a new instance of the DefaultTransactionAttribute (takes
|
|
the EJB approach to rolling back on runtime, but not checked
|
|
exceptions.
|
|
<emphasis>Optional (Defaults to DefaultTransactionAttribute)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-24-co" id="amqp-inbound-channel-adapter-xml-24">
|
|
<para>Sets a Bean reference to an external
|
|
<interface>PlatformTransactionManager</interface> 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:
|
|
|
|
http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/#d0e525
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-channel-adapter-xml-25-co" id="amqp-inbound-channel-adapter-xml-25">
|
|
<para>Tells the <interface>SimpleMessageListenerContainer</interface>
|
|
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".
|
|
<emphasis>Optional (Defaults to 1)</emphasis>.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
<important>
|
|
<para>Even though the Spring Integration JMS and AMQP support is very similar,
|
|
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
|
|
<interface>SimpleMessageListenerContainer</interface> and is message
|
|
driven. In that regard it is more similar to the JMS Message
|
|
Driven Channel Adapter.</para>
|
|
</important>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Outbound Channel Adapter</title>
|
|
|
|
<para>A configuration sample for an AMQP Outbound Channel Adapter is shown
|
|
below with all available parameters.</para>
|
|
<programlisting language="xml"><![CDATA[<int-amqp:outbound-channel-adapter id="outboundAmqp"]]><co id="amqp-outbound-channel-adapter-xml-1-co" linkends="amqp-outbound-channel-adapter-xml-1" /><![CDATA[
|
|
channel="outboundChannel"]]><co id="amqp-outbound-channel-adapter-xml-2-co" linkends="amqp-outbound-channel-adapter-xml-2" /><![CDATA[
|
|
amqp-template="myAmqpTemplate"]]><co id="amqp-outbound-channel-adapter-xml-3-co" linkends="amqp-outbound-channel-adapter-xml-3" /><![CDATA[
|
|
exchange-name=""]]><co id="amqp-outbound-channel-adapter-xml-4-co" linkends="amqp-outbound-channel-adapter-xml-4" /><![CDATA[
|
|
order="1"]]><co id="amqp-outbound-channel-adapter-xml-5-co" linkends="amqp-outbound-channel-adapter-xml-5" /><![CDATA[
|
|
routing-key=""]]><co id="amqp-outbound-channel-adapter-xml-6-co" linkends="amqp-outbound-channel-adapter-xml-6" /><![CDATA[
|
|
routing-key-expression=""]]><co id="amqp-outbound-channel-adapter-xml-7-co" linkends="amqp-outbound-channel-adapter-xml-7" /><![CDATA[
|
|
confirm-correlation-expression=""]]><co id="amqp-outbound-channel-adapter-xml-8-co" linkends="amqp-outbound-channel-adapter-xml-8" /><![CDATA[
|
|
confirm-ack-channel=""]]><co id="amqp-outbound-channel-adapter-xml-9-co" linkends="amqp-outbound-channel-adapter-xml-9" /><![CDATA[
|
|
confirm-nack-channel=""]]><co id="amqp-outbound-channel-adapter-xml-10-co" linkends="amqp-outbound-channel-adapter-xml-10" /><![CDATA[
|
|
return-channel=""]]><co id="amqp-outbound-channel-adapter-xml-11-co" linkends="amqp-outbound-channel-adapter-xml-11" /><![CDATA[/>]]>
|
|
</programlisting>
|
|
<para>
|
|
<calloutlist>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-1-co" id="amqp-outbound-channel-adapter-xml-1">
|
|
<para>Unique ID for this adapter.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-2-co" id="amqp-outbound-channel-adapter-xml-2">
|
|
<para>Message Channel to which Messages should be sent
|
|
in order to have them converted and published to an
|
|
AMQP Exchange.
|
|
<emphasis>Required</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-3-co" id="amqp-outbound-channel-adapter-xml-3">
|
|
<para>Bean Reference to the configured AMQP Template
|
|
<emphasis>Optional (Defaults to "amqpTemplate")</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-4-co" id="amqp-outbound-channel-adapter-xml-4">
|
|
<para>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.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-5-co" id="amqp-outbound-channel-adapter-xml-5">
|
|
<para>The order for this consumer when multiple
|
|
consumers are registered thereby enabling load-
|
|
balancing and/or failover.
|
|
<emphasis>Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE])</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-6-co" id="amqp-outbound-channel-adapter-xml-6">
|
|
<para>The fixed routing-key to use when sending Messages. By
|
|
default, this will be an empty String.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-7-co" id="amqp-outbound-channel-adapter-xml-7">
|
|
<para>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.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-8-co" id="amqp-outbound-channel-adapter-xml-8">
|
|
<para>An expression defining correlation data. When provided, this configures the underlying
|
|
amqp template to receive publisher confirms. Requires a RabbitTemplate and a
|
|
CachingConnectionFactory with publisherConfirms enabled. When a publisher confirm
|
|
is received, it is written to either the confirm-ack-channel, or the confirm-nack-channel,
|
|
depending on the confirmation type. The payload of the confirm is the correlation data as
|
|
defined by this expression and the message will have a header 'amqp_publishConfirm' set to
|
|
true (ack) or false (nack). Examples: "headers['myCorrelationData']", "payload".
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-9-co" id="amqp-outbound-channel-adapter-xml-9">
|
|
<para>The channel to which positive (ack) publisher confirms are sent; payload is
|
|
the correlation data defined by the <emphasis>confirm-correlation-expression</emphasis>.
|
|
<emphasis>Optional, default=nullChannel</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-10-co" id="amqp-outbound-channel-adapter-xml-10">
|
|
<para>The channel to which negative (nack) publisher confirms are sent; payload is
|
|
the correlation data defined by the <emphasis>confirm-correlation-expression</emphasis>.
|
|
<emphasis>Optional, default=nullChannel</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-channel-adapter-xml-11-co" id="amqp-outbound-channel-adapter-xml-11">
|
|
<para>The channel to which returned messages are sent. When provided, the underlying amqp template
|
|
is configured to return undeliverable messages. The message will be constructed from the
|
|
data received from amqp, with the following additional headers: <emphasis>amqp_returnReplyCode,
|
|
amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey</emphasis>.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Inbound Gateway</title>
|
|
<para>A configuration sample for an AMQP Inbound Gateway is shown
|
|
below with all available parameters.</para>
|
|
<programlisting language="xml"><![CDATA[<int-amqp:inbound-gateway id="inboundGateway"]]><co id="amqp-inbound-gateway-adapter-xml-1-co" linkends="amqp-inbound-gateway-adapter-xml-1" /><![CDATA[
|
|
request-channel="myRequestChannel"]]><co id="amqp-inbound-gateway-adapter-xml-2-co" linkends="amqp-inbound-gateway-adapter-xml-2" /><![CDATA[
|
|
queue-names="si.test.queue"]]><co id="amqp-inbound-gateway-adapter-xml-3-co" linkends="amqp-inbound-gateway-adapter-xml-3" /><![CDATA[
|
|
advice-chain=""]]><co id="amqp-inbound-gateway-adapter-xml-4-co" linkends="amqp-inbound-gateway-adapter-xml-4" /><![CDATA[
|
|
concurrent-consumers="1"]]><co id="amqp-inbound-gateway-adapter-xml-5-co" linkends="amqp-inbound-gateway-adapter-xml-5" /><![CDATA[
|
|
connection-factory="connectionFactory"]]><co id="amqp-inbound-gateway-adapter-xml-6-co" linkends="amqp-inbound-gateway-adapter-xml-6" /><![CDATA[
|
|
reply-channel="myReplyChannel"]]><co id="amqp-inbound-gateway-adapter-xml-7-co" linkends="amqp-inbound-gateway-adapter-xml-7" /><![CDATA[/>]]>
|
|
</programlisting>
|
|
<para>
|
|
<calloutlist>
|
|
<callout arearefs="amqp-inbound-gateway-adapter-xml-1-co" id="amqp-inbound-gateway-adapter-xml-1">
|
|
<para>Unique ID for this adapter.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-gateway-adapter-xml-2-co" id="amqp-inbound-gateway-adapter-xml-2">
|
|
<para>Message Channel to which converted Messages should be sent.
|
|
<emphasis>Required</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-gateway-adapter-xml-3-co" id="amqp-inbound-gateway-adapter-xml-3">
|
|
<para>Names of the AMQP Queues from which Messages should be consumed (comma-separated list).
|
|
<emphasis>Required</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-gateway-adapter-xml-4-co" id="amqp-inbound-gateway-adapter-xml-4">
|
|
<para>Extra AOP Advice(s) to handle cross cutting behavior associated with this Inbound Gateway.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-gateway-adapter-xml-5-co" id="amqp-inbound-gateway-adapter-xml-5">
|
|
<para>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.
|
|
<emphasis>Optional (Defaults to 1)</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-gateway-adapter-xml-6-co" id="amqp-inbound-gateway-adapter-xml-6">
|
|
<para>Bean reference to the RabbitMQ ConnectionFactory.
|
|
<emphasis>Optional (Defaults to 'connectionFactory')</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-inbound-gateway-adapter-xml-7-co" id="amqp-inbound-gateway-adapter-xml-7">
|
|
<para>Message Channel where reply Messages will be expected.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Outbound Gateway</title>
|
|
<para>A configuration sample for an AMQP Outbound Gateway is shown
|
|
below with all available parameters.</para>
|
|
<programlisting language="xml"><![CDATA[<int-amqp:outbound-gateway id="inboundGateway"]]><co id="amqp-outbound-gateway-adapter-xml-1-co" linkends="amqp-outbound-gateway-adapter-xml-1" /><![CDATA[
|
|
request-channel="myRequestChannel"]]><co id="amqp-outbound-gateway-adapter-xml-2-co" linkends="amqp-outbound-gateway-adapter-xml-2" /><![CDATA[
|
|
amqp-template=""]]><co id="amqp-outbound-gateway-adapter-xml-3-co" linkends="amqp-outbound-gateway-adapter-xml-3" /><![CDATA[
|
|
exchange-name=""]]><co id="amqp-outbound-gateway-adapter-xml-4-co" linkends="amqp-outbound-gateway-adapter-xml-4" /><![CDATA[
|
|
order="1"]]><co id="amqp-outbound-gateway-adapter-xml-5-co" linkends="amqp-outbound-gateway-adapter-xml-5" /><![CDATA[
|
|
reply-channel=""]]><co id="amqp-outbound-gateway-adapter-xml-6-co" linkends="amqp-outbound-gateway-adapter-xml-6" /><![CDATA[
|
|
routing-key=""]]><co id="amqp-outbound-gateway-adapter-xml-7-co" linkends="amqp-outbound-gateway-adapter-xml-7" /><![CDATA[
|
|
routing-key-expression=""]]><co id="amqp-outbound-gateway-adapter-xml-8-co" linkends="amqp-outbound-gateway-adapter-xml-8" /><![CDATA[
|
|
return-channel=""]]><co id="amqp-outbound-gateway-adapter-xml-9-co" linkends="amqp-outbound-gateway-adapter-xml-9" /><![CDATA[/>]]>
|
|
</programlisting>
|
|
<para>
|
|
<calloutlist>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-1-co" id="amqp-outbound-gateway-adapter-xml-1">
|
|
<para>Unique ID for this adapter.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-2-co" id="amqp-outbound-gateway-adapter-xml-2">
|
|
<para>Message Channel to which Messages should be sent
|
|
in order to have them converted and published to an
|
|
AMQP Exchange.
|
|
<emphasis>Required</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-3-co" id="amqp-outbound-gateway-adapter-xml-3">
|
|
<para>Bean Reference to the configured AMQP Template
|
|
<emphasis>Optional (Defaults to "amqpTemplate")</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-4-co" id="amqp-outbound-gateway-adapter-xml-4">
|
|
<para>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.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-5-co" id="amqp-outbound-gateway-adapter-xml-5">
|
|
<para>The order for this consumer when multiple
|
|
consumers are registered thereby enabling load-
|
|
balancing and/or failover.
|
|
<emphasis>Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE])</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-6-co" id="amqp-outbound-gateway-adapter-xml-6">
|
|
<para>Message Channel to which replies should be sent after
|
|
being received from an AQMP Queue and converted.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-7-co" id="amqp-outbound-gateway-adapter-xml-7">
|
|
<para>The routing-key to use when sending Messages. By default,
|
|
this will be an empty String.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-8-co" id="amqp-outbound-gateway-adapter-xml-8">
|
|
<para>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.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="amqp-outbound-gateway-adapter-xml-9-co" id="amqp-outbound-gateway-adapter-xml-9">
|
|
<para>The channel to which returned messages are sent. When provided, the underlying amqp template
|
|
is configured to return undeliverable messages. The message will be constructed from the
|
|
data received from amqp, with the following additional headers: <emphasis>amqp_returnReplyCode,
|
|
amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey</emphasis>.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
<note>
|
|
<para>Prior to Spring Integration 2.2, and Spring AMQP 1.1, the outbound gateway used a new, temporary,
|
|
reply queue for each request. This is still the default, but now the RabbitTemplate can be configured
|
|
with a specific queue for replies; headers are added to the outbound message for request/reply correlation.
|
|
It is important that the consuming application returns these headers unchanged. The headers are
|
|
<classname>spring_reply_correlation</classname> and <classname>spring_reply_to</classname>. If
|
|
the consuming application is a Spring Integration application, these headers will be managed
|
|
automatically, including the case where that application might send a request/reply to a third
|
|
application using an outbound gateway.</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>AMQP Backed Message Channels</title>
|
|
|
|
<para>
|
|
There are two Message Channel implementations available. One is point-to-point, and the other is publish/subscribe.
|
|
Both of these channels provide a wide range of configuration attributes for the underlying AmqpTemplate and
|
|
SimpleMessageListenerContainer as you have seen on the Channel Adapters and Gateways. However, the examples we'll
|
|
show here are going to have minimal configuration. Explore the XML schema to view the available attributes.
|
|
</para>
|
|
<para>
|
|
A point-to-point channel would look like this:
|
|
<programlisting language="xml"><![CDATA[<int-amqp:channel id="p2pChannel"/>]]></programlisting>
|
|
Under the covers a Queue named "si.p2pChannel" would be declared, and this channel will send to
|
|
that Queue (technically by sending to the no-name Direct Exchange with a routing key that matches this Queue's name).
|
|
This channel will also register a consumer on that Queue. If for some reason, you want the Queue to be "pollable"
|
|
instead of message-driven, then simply provide the "message-driven" flag with a value of false:
|
|
<programlisting language="xml"><![CDATA[<int-amqp:channel id="p2pPollableChannel" message-driven="false"/>]]></programlisting>
|
|
</para>
|
|
<para>
|
|
A publish/subscribe channel would look like this:
|
|
<programlisting language="xml"><![CDATA[<int-amqp:publish-subscribe-channel id="pubSubChannel"/>]]></programlisting>
|
|
Under the covers a Fanout Exchange named "si.fanout.pubSubChannel" would be declared, and this channel will send
|
|
to that Fanout Exchange. This channel will also declare a server-named exclusive, autodelete, non-durable Queue
|
|
and bind that to the Fanout Exchange while registering a consumer on that Queue to receive Messages. There is no
|
|
"pollable" option for a publish-subscribe-channel; it must be message-driven.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>AMQP Samples</title>
|
|
<para>
|
|
To experiment with the AMQP adapters, check out the samples available in
|
|
the Spring Integration Samples Git repository at:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><ulink url="https://github.com/SpringSource/spring-integration-samples">
|
|
https://github.com/SpringSource/spring-integration-samples</ulink>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
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
|
|
uses RabbitMQ (<ulink url="http://www.rabbitmq.com/">http://www.rabbitmq.com/</ulink>).
|
|
</para>
|
|
<note>
|
|
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:
|
|
<ulink url="http://www.rabbitmq.com/install.html">
|
|
http://www.rabbitmq.com/install.html
|
|
</ulink>
|
|
</note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
The image belows illustrates the basic set of Spring Integration components
|
|
used in this sample.
|
|
</para>
|
|
<mediaobject>
|
|
<imageobject role="fo">
|
|
<imagedata fileref="images/spring-integration-amqp-sample-graph.png" format="PNG" align="center" scalefit="1" width="100%" contentdepth="100%"/>
|
|
</imageobject>
|
|
<imageobject role="html">
|
|
<imagedata fileref="images/spring-integration-amqp-sample-graph.png" format="PNG" align="center" scalefit="1" width="100%" contentdepth="100%"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
<caption>The Spring Integration graph of the AMQP sample</caption>
|
|
</section>
|
|
</chapter>
|