Expression evaluating request handler advice
Evaluates a configurable SpEL expression on successful and/or failed attempts.
This advice provides a mechanism to evaluate an expression on the original inbound message sent to the endpoint. Separate expressions are available to be evaluated, either after success, or failure. Optionally, a message containing the evaluation result, together with the input message, can be sent to a message channel.
A typical use case for this advice might be with an FTP outbound channel adapter, perhaps to move the file to one directory if the transfer was successful, or to another directory if it fails.
This advice has properties to set an expression when successful, an expression for failures, and corresponding channels for each. For the successful case, the message sent to the success channel is an AdviceMessage
, with the payload being the result of the expression evaluation, and an additional property inputMessage
which contains the original message sent to the handler. A message sent to the failure channel (when the handler throws an exception) is an ErrorMessage
with a payload of MessageHandlingExpressionEvaluatingAdviceException
. Like all MessagingExceptions
, this payload has failedMessage
and cause
properties, as well as an additional property evaluationResult
, containing the result of the expression evaluation.
On success expression
SpEL expression that will be executed on the input message when the message handler invocation was successful, for example headers.file_originalFile.delete()
.
Optional
Success channel
If the on success expression evaluation returned a result (i.e. not 'null'; can also be an evaluation exception), an AdviceMessage
is send to this message channel.
An AdviceMessage
contains the evaluation result in its payload and the inputMessage
property (i.e. Java class field; not a header!) contains the original message that was sent to the message handler.
Can only be used when the on success expression is specified.
Optional
On failure expression
SpEL expression that will be executed on the input message when the message handler invocation has failed, for example headers.file_originalFile.renameTo(new java.io.File(${backup.dir} + '/' + headers.file_name))
.
Optional
Failure channel
If the on failure expression evaluation returned a result (i.e. not 'null'; can also be an evaluation exception), an ErrorMessage
is send to this message channel.
The ErrorMessage
will have a payload of type MessageHandlingExpressionEvaluatingAdviceException
, which is a specialized Exception
that also provides properties failedMessage
(contains the original message that was sent to the message handler) and evaluationResult
(contains the evaluation result of the on failure expression).
Can only be used when the on failure expression is specified.
Optional.
Trap exception
If true
, any exception will be caught and null
returned. This would basically prevent the normal error handling from being triggered, but can cause other errors to occur that will trigger the error handling anyway. For example, returning null
in an outbound gateway with requires reply enabled, will result in a ReplyRequiredException
.
Note that this does not cover exceptions that might occur while trying to evaluation the on failure expression. Whether or not it covers exceptions that might occur while trying to evaluation the on success expression is configurable with the propagate evaluation failures setting.
Default is false
.
Return failure expression result
If true
, the result of evaluating the on failure expression will be returned as the result instead of throwing an exception or returning null
.
Note that the evaluation result can also be null
or an evaluation exception.
Default is false
.
Propagate evaluation failures
If true
and an on success expression evaluation fails with an exception, the exception will be thrown to the caller. If false
, the exception is caught.
Ignored for on failure expression evaluation: the original exception will be propagated (unless trap exception or return failure expression result is true
).
Default is false
.