diff --git a/src/reference/docbook/jms.xml b/src/reference/docbook/jms.xml index 0e9b2d0c05..3c1f9b373b 100644 --- a/src/reference/docbook/jms.xml +++ b/src/reference/docbook/jms.xml @@ -22,7 +22,17 @@ capable of sending a return value to the "reply-to" Destination as provided by the received Message. The outbound Gateway sends a JMS Message to a "request-destination" and then receives a reply Message. The "reply-destination" reference (or "reply-destination-name") can be configured explicitly or else the outbound gateway will use a - JMS TemporaryQueue. + JMS TemporaryQueue. + + + Prior to Spring Integration 2.2, if necessary, a TemporaryQueue + was created (and removed) + for each request/reply. Beginning with Spring Integration 2.2, the outbound gateway + can be configured to use + a MessageListener container to receive replies instead of directly + using a new (or cached) Consumer to receive the reply for each request. When so + configured, and no explicit reply destination is provided, a single TemporaryQueue + is used for each gateway instead of one for each request.
@@ -192,12 +202,25 @@ The outbound Gateway creates JMS Messages from Spring Integration Messages and then sends to a 'request-destination'. It will then handle the JMS reply Message either by using a selector to receive from the 'reply-destination' that you configure, or if no 'reply-destination' is provided, - it will create JMS TemporaryQueues. Notice that the "reply-channel" is also provided. - TemporaryQueues. + + + Using a reply-destination (or reply-destination-name), together with + a CachingConnectionFactory with cacheConsumers set to + true, can cause Out of Memory conditions. This is because each request gets a new consumer with + a new selector (selecting on the correlation-key value, or on the sent JMSMessageID when there is no correlation-key). + Given that these selectors are unique, they will remain in the cache unused after the current request completes. + + + If you specify a reply destination, you are advised to NOT use cached consumers. Alternatively, + consider using a <reply-listener/> as described below. + + + + ]]> - The 'outbound-gateway' payload extraction properties are inversely related to those of the 'inbound-gateway' (see the discussion above). That means that the 'extract-request-payload' property value @@ -206,6 +229,56 @@ JMS Message that is received as a reply and then converted into a Spring Integration Message to be subsequently sent to the 'reply-channel' as shown in the example configuration above. + <reply-listener/> + + Spring Integration 2.2 introduced an alternative technique for handling replies. + If you add a + <reply-listener/> child element to the gateway, instead of creating a consumer for + each reply, a MessageListener container is used to receive the replies + and hand them over to the requesting thread. This provides a number of performance benefits + as well as alleviating the cached consumer memory utilization problem described in the caution + above. + + + When using a <reply-listener/>, instead of creating a TemporaryQueue + for each request, a single TemporaryQueue is used + (the gateway will create an additional TemporaryQueue, as + necessary, if the connection to the broker is lost and recovered). + + + When using a correlation-key, multiple gateways can share the same + reply destination because the listener container uses a selector that is unique + to each gateway. + + + + If you specify a reply listener, and specify a reply destination (or reply destination name), + but provide NO correlation key, the gateway will log a warning and fall back to pre-2.2 + behavior. This is because there is no way to configure a selector in this case, thus there is + no way to avoid a reply going to a different gateway that might be configured with the + same reply destination. + + + Note that, in this situation, a new consumer is used for each request, and + consumers can build up in memory as described in the + caution above; therefore cached consumers should not be used in this case. + + + + +]]> + + In the above example, a reply listener with default attributes is used. The listener is + very lightweight and it is anticipated that, in most cases, only a single consumer will + be needed. However, attributes such as concurrent-consumers, + max-concurrent-consumers etc., can be added. Refer to the + schema for a complete list of supported attributes, together with the + Spring JMS documentation + for their meanings. +
diff --git a/src/reference/docbook/whats-new.xml b/src/reference/docbook/whats-new.xml index 016bb2ae86..e5f4f5e289 100644 --- a/src/reference/docbook/whats-new.xml +++ b/src/reference/docbook/whats-new.xml @@ -153,6 +153,14 @@ For more information see .
+
+ JMS Oubound Gateway Improvements + + The JMS Outbound Gateway can now be configured to use a + MessageListener container to receive + replies. This can improve performance of the gateway. + +