10. AMQP Support

10. AMQP Support
Prev	Part IV. Integration Endpoints	Next

10.1 Introduction

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
Outbound Channel Adapter
Inbound Gateway
Outbound Gateway

Spring Integration also provides a point-to-point Message Channel as well as a 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 (http://static.springsource.org/spring/docs/current/spring-framework-reference/html/jms.html).

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.

Tip

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: http://static.springsource.org/spring-amqp/reference/html/

10.2 Inbound Channel Adapter

A configuration sample for an AMQP Inbound Channel Adapter is shown below.

<int-amqp:inbound-channel-adapter
                                  id="inboundAmqp"
                                  channel="inboundChannel"
                                  queue-names="si.test.queue"
                                  acknowledge-mode="AUTO"
                                  advice-chain=""
                                  channel-transacted=""
                                  concurrent-consumers=""
                                  connection-factory=""
                                  error-channel=""
                                  expose-listener-channel=""
                                  header-mapper=""
                                  mapped-request-headers=""
                                  mapped-reply-headers=""
                                  listener-container=""
                                  message-converter=""
                                  message-properties-converter=""(16)
                                  phase=""(17)
                                  prefetch-count=""(18)
                                  receive-timeout=""(19)
                                  recovery-interval=""(20)
                                  shutdown-timeout=""(21)
                                  task-executor=""(22)
                                  transaction-attribute=""(23)
                                  transaction-manager=""(24)
                                  tx-size=""(25)/>

Unique ID for this adapter. Optional.

Message Channel to which converted Messages should be sent. Required.

Names of the AMQP Queues from which Messages should be consumed (comma-separated list). Required.

Acknowledge Mode for the MessageListenerContainer. When set to MANUAL, the delivery tag and channel are provided in message headers amqp_deliveryTag and amqp_channel respectively; the user application is responsible for acknowledgement. NONE means no acknowledgements (autoAck); AUTO means the adapter's container will acknowledge when the downstream flow completes. Optional (Defaults to AUTO) see Section 10.4, “Inbound Endpoint Acknowledge Mode”.

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, 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 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 exposed to a registered ChannelAwareMessageListener. Optional (Defaults to true).

AmqpHeaderMapper 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 explicitly identified via 'requestHeaderNames' and/or 'replyHeaderNames' properties of this DefaultAmqpHeaderMapper. 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 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 own MessageListener configured. Optional.

Note

Note that when configuring an external container, you cannot use the Spring AMQP namespace to define the container. This is because the namespace requires at least one <listener/> element. In this environment, the listener is internal to the adapter. For this reason, you must define the container using a normal Spring <bean/> definition, such as:

<bean id="container"
 class="org.springframework.amqp.rabbit.listener.SimpleMessageListenerContainer">
	<property name="connectionFactory" ref="connectionFactory" />
	<property name="queueNames" value="foo.queue" />
	<property name="defaultRequeueRejected" value="false"/>
</bean>

The MessageConverter to use when receiving AMQP Messages. Optional.

(16)

The MessagePropertiesConverter to use when receiving AMQP Messages. Optional.

(17)

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.

(18)

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).

(19)

Receive timeout in milliseconds. Optional (Defaults to 1000).

(20)

Specifies the interval between recovery attempts of the underlying SimpleMessageListenerContainer (in milliseconds). Optional (Defaults to 5000).

(21)

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).

(22)

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).

(23)

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).

(24)

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: http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/#d0e525 Optional.

(25)

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).

Important

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 SimpleMessageListenerContainer and is message driven. In that regard it is more similar to the JMS Message Driven Channel Adapter.

10.3 Inbound Gateway

A configuration sample for an AMQP Inbound Gateway is shown below.

<int-amqp:inbound-gateway
                          id="inboundGateway"
                          request-channel="myRequestChannel"
                          queue-names="si.test.queue"
                          advice-chain=""
                          concurrent-consumers="1"
                          connection-factory="connectionFactory"
                          acknowledge-mode="AUTO"
                          reply-channel="myReplyChannel"/>

	Unique ID for this adapter. Optional.
	Message Channel to which converted Messages should be sent. Required.
	Names of the AMQP Queues from which Messages should be consumed (comma-separated list). Required.
	Extra AOP Advice(s) to handle cross cutting behavior associated with this Inbound Gateway. 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, stick with 1 consumer for low-volume queues. Optional (Defaults to 1).
	Bean reference to the RabbitMQ ConnectionFactory. Optional (Defaults to 'connectionFactory').
	Acknowledge Mode for the MessageListenerContainer. When set to MANUAL, the delivery tag and channel are provided in message headers `amqp_deliveryTag` and `amqp_channel` respectively; the user application is responsible for acknowledgement. NONE means no acknowledgements (autoAck); AUTO means the adapter's container will acknowledge when the downstream flow completes. Optional (Defaults to AUTO) see Section 10.4, “Inbound Endpoint Acknowledge Mode”.
	Message Channel where reply Messages will be expected. Optional.

See the note in Section 10.2, “Inbound Channel Adapter” about configuring the listener-container attribute.

10.4 Inbound Endpoint Acknowledge Mode

By default the inbound endpoints use acknowledge mode AUTO, which means the container automatically acks the message when the downstream integration flow completes (or a message is handed off to another thread using a QueueChannel or ExecutorChannel). Setting the mode to NONE configures the consumer such that acks are not used at all (the broker automatically acks the message as soon as it is sent). Setting the mode to MANUAL allows user code to ack the message at some other point during processing. To support this, with this mode, the endpoints provide the Channel and deliveryTag in the amqp_channel and amqp_deliveryTag headers respectively.

You can perform any valid rabbit command on the Channel but, generally, only basicAck and basicNack (or basicReject) would be used. In order to not interfere with the operation of the container, you should not retain a reference to the channel and just use it in the context of the current message.

	Note
	Since the `Channel` is a reference to a "live" object, it cannot be serialized and will be lost if a message is persisted.

This is an example of how you might use MANUAL acknowledgement:

@ServiceActivator(inputChannel = "foo", outputChannel = "bar")
public Object handle(@Payload String payload, @Header(AmqpHeaders.CHANNEL) Channel channel,
        @Header(AmqpHeaders.DELIVERY_TAG) Long deliveryTag) throws Exception {

    // Do some processing

    if (allOK) {
        channel.basicAck(deliveryTag, false);

        // perhaps do some more processing

    }
    else {
        channel.basicNack(deliveryTag, false, true);
    }
    return someResultForDownStreamProcessing;
}

10.5 Outbound Channel Adapter

A configuration sample for an AMQP Outbound Channel Adapter is shown below.

<int-amqp:outbound-channel-adapter id="outboundAmqp"
                               channel="outboundChannel"
                               amqp-template="myAmqpTemplate"
                               exchange-name=""
                               order="1"
                               routing-key=""
                               routing-key-expression=""
                               default-delivery-mode""
                               confirm-correlation-expression=""
                               confirm-ack-channel=""
                               confirm-nack-channel=""
                               return-channel=""/>

Unique ID for this adapter. Optional.

Message Channel to which Messages should be sent in order to have them converted and published to an AMQP Exchange. Required.

Bean Reference to the configured AMQP Template 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 default, no-name Exchange. Optional.

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]).

The fixed routing-key to use when sending Messages. By default, this will be an empty String. Optional.

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.

The default delivery mode for messages; 'PERSISTENT' or 'NON_PERSISTENT'. Overridden if the 'header-mapper' sets the delivery mode. The 'DefaultHeaderMapper' sets the value if the Spring Integration message header amqp_deliveryMode is present. If this attribute is not supplied and the header mapper doesn't set it, the default depends on the underlying spring-amqp 'MessagePropertiesConverter' used by the 'RabbitTemplate'. If that is not customized at all, the default is 'PERSISTENT'. Optional.

An expression defining correlation data. When provided, this configures the underlying amqp template to receive publisher confirms. Requires a dedicated RabbitTemplate and a CachingConnectionFactory with the publisherConfirms property set to true. When a publisher confirm is received, and correlation data is supplied, 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". Optional.

The channel to which positive (ack) publisher confirms are sent; payload is the correlation data defined by the confirm-correlation-expression. Optional, default=nullChannel.

The channel to which negative (nack) publisher confirms are sent; payload is the correlation data defined by the confirm-correlation-expression. Optional, default=nullChannel.

The channel to which returned messages are sent. When provided, the underlying amqp template is configured to return undeliverable messages to the adapter. The message will be constructed from the data received from amqp, with the following additional headers: amqp_returnReplyCode, amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey. Optional.

	Important
	Using a `return-channel` requires a `RabbitTemplate` with the `mandatory` property set to `true`, and a `CachingConnectionFactory` with the `publisherReturns` property set to `true`. When using multiple outbound endpoints with returns, a separate `RabbitTemplate` is needed for each endpoint.

10.6 Outbound Gateway

A configuration sample for an AMQP Outbound Gateway is shown below.

<int-amqp:outbound-gateway id="inboundGateway"
                           request-channel="myRequestChannel"
                           amqp-template=""
                           exchange-name=""
                           order="1"
                           reply-channel=""
                           routing-key=""
                           routing-key-expression=""
                           default-delivery-mode""
                           return-channel=""/>

Unique ID for this adapter. Optional.

Message Channel to which Messages should be sent in order to have them converted and published to an AMQP Exchange. Required.

Bean Reference to the configured AMQP Template 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 default, no-name Exchange. Optional.

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 being received from an AQMP Queue and converted. Optional.

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'). By default, this will be an empty String. Optional.

The default delivery mode for messages; 'PERSISTENT' or 'NON_PERSISTENT'. Overridden if the 'header-mapper' sets the delivery mode. The 'DefaultHeaderMapper' sets the value if the Spring Integration message header amqp_deliveryMode is present. If this attribute is not supplied and the header mapper doesn't set it, the default depends on the underlying spring-amqp 'MessagePropertiesConverter' used by the 'RabbitTemplate'. If that is not customized at all, the default is 'PERSISTENT'. Optional.

The channel to which returned messages are sent. When provided, the underlying amqp template is configured to return undeliverable messages to the gateway. The message will be constructed from the data received from amqp, with the following additional headers: amqp_returnReplyCode, amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey. Optional.

	Important
	Using a `return-channel` requires a `RabbitTemplate` with the `mandatory` property set to `true`, and a `CachingConnectionFactory` with the `publisherReturns` property set to `true`. When using multiple outbound endpoints with returns, a separate `RabbitTemplate` is needed for each endpoint.

Note

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 spring_reply_correlation and spring_reply_to. 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.

10.7 AMQP Backed Message Channels

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.

A point-to-point channel would look like this:

<int-amqp:channel id="p2pChannel"/>

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:

<int-amqp:channel id="p2pPollableChannel"  message-driven="false"/>

A publish/subscribe channel would look like this:

<int-amqp:publish-subscribe-channel id="pubSubChannel"/>

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.

10.8 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 DefaultAmqpHeaderMapper.

	Tip
	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

10.9 AMQP Samples

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 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 (http://www.rabbitmq.com/).

	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: 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.

The image belows illustrates the basic set of Spring Integration components used in this sample.

The Spring Integration graph of the AMQP sample

Prev	Up	Next
9. Endpoint Quick Reference Table	Home	11. Spring ApplicationEvent Support