Adding Behavior to Endpoints
Prior to Spring Integration 2.2, you could add behavior to an entire Integration flow by adding
an AOP Advice to a poller's <advice-chain /> element. However, let's say
you want to retry, say, just a ReST Web Service call, and not any downstream endpoints.
For example, consider the following flow:
inbound-adapter->poller->http-gateway1->http-gateway2->jdbc-outbound-adapter
If you configure some retry-logic into an advice chain on the poller, and, the call to
http-gateway2 failed because of a network glitch, the retry would cause
both http-gateway1 and http-gateway2 to be called
a second time. Similarly, after a transient failure in the
jdbc-outbound-adapter, both http-gateways
would be called a second time before again calling the jdbc-outbound-adapter.
Spring Integration 2.2 adds the ability to add behavior to individual endpoints. This is achieved
by the addition of the <request-handler-advice-chain /> element to many endpoints. For example:
inputMessage which contains the original message sent to the handler. A message
sent to the failureChannel (when the handler throws an excecption)
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.
Custom Advice Classes
In addition to the provided Advice classes above, you can implement your own Advice classes. While you can
provide any implementation of org.aopalliance.aop.Advice, it is generally recommended
that you subclass o.s.i.handler.advice.AbstractRequestHandlerAdvice.
This has the benefit of avoiding writing low-level Aspect Oriented Programming code as well
as providing a starting point that is specifically tailored for use in this environment.
Subclasses need to implement the doInvoke() method:
message) throws Exception;]]>
The callback parameter is simply a convenience to avoid subclasses dealing with AOP directly; invoking the
callback.execute()
method invokes the message handler.
The target parameter is provided for those subclasses that need to maintain state for a
specific handler, perhaps by maintaining that state in a Map, keyed by the target.
This allows the same advice to be applied to multiple handlers. The
RequestHandlerCircuitBreakerAdvice uses this to
keep circuit breaker state for each handler.
The message parameter is the message that will be sent to the handler.
While the advice cannot modify the message
before invoking the handler, it can modify the payload (if it has mutable properties). Typically, an advice would
use the message for logging and/or to send a copy of the message somewhere before or after invoking the
handler.
The return value would normally be the value returned by callback.execute();
but the advice does have the
ability to modify the return value. Note that only AbstractReplyProducingMessageHandlers
return a value.
message) throws Exception {
// add code before the invocation
Object result = callback.execute();
// add code after the invocation
return result;
}
}]]>
In addition to the execute() method, the ExecutionCallback provides
an additional method cloneAndExecute(). This method must be used in cases where the invocation
might be called multiple times within a single execution of doInvoke(), such as in the
RequestHandlerRetryAdvice. This is required because the Spring AOP
org.springframework.aop.framework.ReflectiveMethodInvocation object maintains state of which
advice in a chain was last invoked; this state must be reset for each call.
For more information, see the
ReflectiveMethodInvocation JavaDocs.
Other Advice Chain Elements
While the abstract class mentioned above is provided as a convenience, you can add any
Advice to the chain, including a transaction advice.
Advising Filters
There is an additional consideration when advising Filters. By default, any discard
actions (when the filter returns false) are performed within the scope of the
advice chain. This could include all the flow downstream of the discard channel.
So, for example if an element downstream of the discard-channel throws an exception,
and there is a retry advice, the process will be retried. This is also the case if
throwExceptionOnRejection is set to true (the exception is thrown within the
scope of the advice).
Setting discard-within-advice to "false" modifies this behavior and the discard
(or exception) occurs after the advice chain is called.
Advising Endpoints Using Annotations
When configuring certain endpoints using annotations (@Filter, @ServiceActivator,
@Splitter, and @Transformer), you can supply a bean name for the advice
chain in the adviceChain attribute. In addition, the @Filter annotation
also has the discardWithinAdvice attribute, which can be used to configure the discard
behavior as discussed in . An example with the discard being
performed after the advice is shown below.
Ordering Advices within an Advice Chain
Advice classes are "around" advices and are applied in a nested fashion. The first advice is the
outermost, the last advice the innermost (closest to the handler being advised). It is important
to put the advice classes in the correct order to achieve the functionality you desire.
For example, let's say you want to add a retry advice and a transaction advice.
You may want to place the retry advice advice first, followed by the transaction advice.
Then, each retry will be performed in a new transaction. On the other hand, if you want all the attempts,
and any recovery operations (in the retry RecoveryCallback), to be scoped within
the transaction, you would put the transaction advice first.