JMS outbound gateway
Sends JMS request messages to a connection and receives JMS reply messages.
Sends JMS request messages to the specified request destination at the connection created by the connection factory, and receives JMS reply messages from the specified reply destination using the same connection factory.
Connection factory
Reference to a JMS connection factory used for creating connections.
Required
Note: The connection factory should return pooled connections as well as pooled sessions and message producers, otherwise performance of JMS operations is going to suffer. Consider using a caching connection factory to achieve this.
Request destination name
Name of the destination to which JMS request messages will be sent (typically the name of a JMS queue or topic).
This attribute is mutually exclusive with request destination expression.
Request pub-sub domain
Whether the publish-subscribe domain (JMS Topics) should be used for resolving the request destination name or not.
Default is false, indicating that the point-to-point domain (JMS Queues) should be used.
Reply destination name
Name of the destination from which JMS reply messages will be received (typically the name of a JMS queue or topic).
If not provided, JMS temporary queues will be created.
Reply pub-sub domain
Whether the publish-subscribe domain (JMS Topics) should be used for resolving the reply destination name or not.
Default is false, indicating that the point-to-point domain (JMS Queues) should be used.
Extract request payload
Applies to the Spring Integration message that is being converted into a JMS message to be sent as a request.
If you want to pass the whole Spring Integration message (as the body of a JMS ObjectMessage
) then set this to false
. By default, it is true
such that the Spring Integration message payload will be converted into a JMS message (e.g. String
payload becomes a JMS TextMessage
). In both cases, the message headers will be mapped to JMS headers/properties.
Default is true
.
Extract reply payload
Applies to the JMS message that is received as a reply and then converted into a Spring Integration message.
Determines whether the received JMS message body will be extracted. If false
, the JMS message itself will become the Spring Integration message payload. In both cases, the JMS Message headers/properties will be mapped to message headers.
The default is true
.
Message converter
Reference to a converter for converting the Spring Integration message payload to/from a JMS message.
When not specified, a SimpleMessageConverter will be used. This converter converts a string to a TextMessage, a byte array to a BytesMessage
, a Map to a MapMessage
, and a serializable objectto an ObjectMessage
.
Use a JMS XML Message Converter for XML messages that are not already in a string-representation.
Request destination expression
A SpEL expression to be evaluated at runtime against each Spring Integration request message as the root object. The result should be the request destination name.
This attribute is mutually exclusive with request destination name.
Reply destination expression
A SpEL expression to be evaluated at runtime against each Spring Integration request message as the root object. The result should be the reply destination name.
This attribute is mutually exclusive with reply destination name.
Correlation key
Provide the name of a JMS property that should hold a generated UUID that the receiver of the JMS message would expect to represent the CorrelationID.
When waiting for the reply message, a message selector will be configured to match this property name and the UUID value that was sent in the request.
If no value is provided for this attribute, then the reply consumer's message selector will be expecting the JMSCorrelationID to equal the message ID of the request. If you want to store the outbound correlation UUID value in the actual JMSCorrelationID property, then set this value to "JMSCorrelationID"
; any other value will be treated as a JMS string property.
Note: when using a reply listener the correlation data includes a UUID representing the gateway as well as a message identifier. For this reason, the use of a reply listener requires the specification of a correlation key if an explicit reply destination is provided.
Receive timeout
Timeout for the JMS message consumer to receive the JMS reply message.
Default is 5000
(five seconds).
Reply timeout
Allows you to specify how long (in milliseconds) this gateway will wait for the reply message to be sent successfully to the reply channel before throwing an exception. This attribute only applies when the channel might block, for example when using a bounded queue channel that is currently full.
Also, keep in mind that when sending to a direct channel, the invocation will occur in the sender's thread. Therefore, the failing of the send operation may be caused by other components further downstream.
If not specified, by default the gateway will wait indefinitely.
Explicit QoS enabled
If true, then the values of delivery persistent, priority, and time to live will be used when sending a message. Otherwise, the default values, that may be set administratively, will be used.
Default is false.
Delivery persistent
Specifies whether message delivery should be persistent or non-persistent. This will set the delivery mode accordingly, to either PERSISTENT (true) or NON_PERSISTENT (false).
Since a default value may be defined administratively, this is only used when explicit QoS enabled is set to true.
Default it true (delivery mode PERSISTENT).
Priority
Set the priority of a message when sending.
Since a default value may be defined administratively, this is only used when explicit QoS enabled is set to true.
Default is 4
.
Time to live
Specifies the time-to-live (in milliseconds) of the message when sending.
Since a default value may be defined administratively, this is only used when explicit QoS enabled is set to true.
Default is unlimited (0
): messages will never expire.
Task executor
A reference to a task executor for receiving the replies and handing them over to the sending thread.
Default is a SimpleAsyncTaskExecutor
.
Requires reply
Specify whether this outbound gateway must return a non-null
value, i.e. whether every request message must result in a reply message.
If true
, a ReplyRequiredException
will be thrown when the underlying service returns a null
value.
Default is true
.
Use reply listener
If enabled, 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 (see the cache consumers property of the JMS caching connection factory).
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.
Caution If you specify a reply listener and a reply destination name, but provide no correlation key, the gateway will log a warning and not use a reply listener. 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 above; therefore cached consumers should not be used in this case.
Idle reply listener timeout
When using a reply listener, specify whether the container should be started on-demand and stopped when idle for this time (in seconds). When omitted (or zero or less), the reply container is started/stopped according to the gateway's lifecycle.
Default is empty.
Async
When false
(default), the requesting thread is suspended until a reply is received or a timeout occurs.
When true
, the requesting thread is released and the reply is returned on the listener container thread.
Acknowledge
JMS acknowledge modes:
- Auto (default): automatic message acknowledgment before listener execution; no redelivery in case of exception thrown.
- Client: automatic message acknowledgment after successful listener execution; no redelivery in case of exception thrown.
- Dups-ok: lazy message acknowledgment during or after listener execution; potential redelivery in case of exception thrown.
- Transacted: transactional acknowledgment after successful listener execution; guaranteed redelivery in case of exception thrown.
Concurrent consumers
Specify the number of concurrent consumers to create.
Default is 1
.
Specifying a higher value for this setting will increase the standard level of scheduled concurrent consumers at runtime: This is effectively the minimum number of concurrent consumers which will be scheduled at any given time. This is a static setting; for dynamic scaling, consider specifying the max concurrent consumers setting instead.
Do not raise the number of concurrent consumers for a topic, unless vendor-specific setup measures clearly allow for it. With regular setup, this would lead to concurrent consumption of the same message, which is hardly ever desirable.
Max. concurrent consumers
Specify the maximum number of concurrent consumers to create.
Default is 1
.
If this setting is higher than concurrent consumers, the listener container will dynamically schedule new consumers at runtime, provided that enough incoming messages are encountered. Once the load goes down again, the number of consumers will be reduced to the standard level again.
Raising the number of concurrent consumers is recommendable 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.
Do not raise the number of concurrent consumers for a topic, unless vendor-specific setup measures clearly allow for it. With regular setup, this would lead to concurrent consumption of the same message, which is hardly ever desirable.
Cache level
Specify the level of caching that this listener container is allowed to apply.
Default is CACHE_NONE
if an external transaction manager has been specified (to reobtain all resources freshly within the scope of the external transaction), and CACHE_CONSUMER
otherwise (operating with local JMS resources).
Some J2EE servers only register their JMS resources with an ongoing XA transaction in case of a freshly obtained JMS Connection and Session, which is why this listener container by default does not cache any of those. However, if you want to optimize for a specific server, consider switching this setting to at least CACHE_CONNECTION
or CACHE_SESSION
even in conjunction with an external transaction manager.
Currently known servers that absolutely require CACHE_NONE
for XA transaction processing: JBoss 4. For any others, consider raising the cache level.
Possible cache level values:
0: CACHE_NONE
1: CACHE_CONNECTION
2: CACHE_SESSION
3: CACHE_CONSUMER
Max. messages per task
Specify the maximum number of messages to process in one task. More concretely, this limits the number of message reception attempts per task, which includes receive iterations that did not actually pick up a message until they hit their timeout (see the receive timeout property).
Default is unlimited (-1
) in case of a standard TaskExecutor, reusing the original invoker threads until shutdown (at the expense of limited dynamic scheduling).
In case of a SchedulingTaskExecutor indicating a preference for short-lived tasks, the default is 10
instead. Specify a number of 10 to 100 messages to balance between rather long-lived and rather short-lived tasks here.
Long-lived tasks avoid frequent thread context switches through sticking with the same thread all the way through, while short-lived tasks allow thread pools to control the scheduling. Hence, thread pools will usually prefer short-lived tasks.
Recovery interval
Specifies the interval between recovery attempts, in milliseconds. The default is 5000
ms (five seconds).
Idle consumer limit
Specify the limit for the number of consumers that are allowed to be idle at any given time.
This limit is used to determine if a new invoker should be created. Increasing the limit causes invokers to be created more aggressively. This can be useful to ramp up the number of invokers faster.
The default is 1
, only scheduling a new invoker (which is likely to be idle initially) if none of the existing invokers is currently idle.
Idle task execution limit
Specify the limit for idle executions of a consumer task, not having received any message within its execution. If this limit is reached, the task will shut down and leave receiving to other executing tasks.
The default is 1
, closing idle resources early once a task didn't receive a message. This applies to dynamic scheduling only; see the max concurrent consumers setting. The minimum number of consumers (see concurrent consumers) will be kept around until shutdown in any case.
Within each task execution, a number of message reception attempts (according to the max messages per task setting) will each wait for an incoming message (according to the receive timeout setting). If all of those receive attempts in a given task return without a message, the task is considered idle with respect to received messages. Such a task may still be rescheduled; however, once it reached the specified idle task execution limit, it will shut down (in case of dynamic scaling).
Raise this limit if you encounter too frequent scaling up and down. With this limit being higher, an idle consumer will be kept around longer, avoiding the restart of a consumer once a new load of messages comes in. Alternatively, specify a higher max messages per task and/or receive timeout value, which will also lead to idle consumers being kept around for a longer time (while also increasing the average execution time of each scheduled task).
Receive timeout
Set the timeout to use for receive calls. The default is 1000
ms (one second).
Note: this value needs to be smaller than the transaction timeout used by the transaction manager. Value -1
indicates no timeout at all; however, this is only feasible if not running within a transaction manager.
Request channel
Channel to consume the request messages from.
Required
Reply channel
Channel where reply messages should be sent to.
You can select the nullChannel
here to silently drop the reply messages.
Required
Advice can be added to change the behaviour of this endpoint, for example to add retry logic in case of failures. The following types of advice are available:
Retry advice: allows configuration of sophisticated retry scenarios; this includes specifying policies for retry attemps, backoff periods between attempts and the recovery strategy when retries are exhausted Circuit breaker: if a certain number of consecutive attempts fails, new requests will fail fast and no attempt will be made to invoke the request handler again until some time has expired Expression evaluating advice: general advice that evaluates a configurable SpEL expression on successful and/or failed attempts, and optionally can send a message to a success channel and/or failure channel
By adding multiple advices to this endpoint you can create even more complex combined behaviour. For example, if you add a circuit breaker and a retry advice, you can create a scenario where the circuit breaker only opens when all retries are exhaused. Note that the order of the advice types is important, as switching the order will change the combined behaviour: the first item in the list will be the top of the advice chain, meaning it will be the last advice that is evaluated. Also note that if any advice "traps" exceptions, all advices higher up in the chain won't know about any failures.
Id
Name that uniquely identifies this flow component.
Required