org.mule.runtime.extension.api.runtime.operation

Interface Interceptor

public interface Interceptor

Taps into different phases of the execution of an extension's operation allowing to take different actions depending on the phase.

One instance of each implementation will be created per ConfigurationInstance. Those instances can have lifecycle, can be stateful and can use JSR-330 annotations for dependency injection. However, they MUST be thread-safe and reusable.

Since:

1.0

Method Summary

Modifier and Type	Method and Description
default void	after(OperationContext operationContext, Object result) Executes after the execution of an operation is finished, regardless of it being successful or not.
default void	before(OperationContext operationContext) Executes before the operation is executed.
default Throwable	onError(OperationContext operationContext, RetryRequest retryRequest, Throwable exception) Executes when the execution of an operation threw exception.
default void	onSuccess(OperationContext operationContext, Object result) Executes when an operation was successfully executed.

Method Detail

before

default void before(OperationContext operationContext)
             throws Exception

Executes before the operation is executed.

If this method fails, the exception will be bubbled up right away. No other method in this interceptor will be executed (not even the after(OperationContext, Object), nor any other of the interceptors in line will be executed either. Because of this, no implementation should rely on the execution of any other method in this or other interceptor

Parameters:

operationContext - the OperationContext for the operation to be executed

Throws:

Exception - in case of error

onSuccess

default void onSuccess(OperationContext operationContext,
                       Object result)

Executes when an operation was successfully executed.

Implementations of this method should not fail. If they do throw any exception, it will be logged and ignored.

The after(OperationContext, Object) method is guaranteed to be executed regardless of this method's outcome in this or other involved instances

Parameters:

operationContext - the OperationContext that was used to execute the operation

result - the result of the operation. Can be null if the operation itself returned that.

onError

default Throwable onError(OperationContext operationContext,
                          RetryRequest retryRequest,
                          Throwable exception)

Executes when the execution of an operation threw exception.

This method returns Exception to allow implementations to decorate, enrich or even replace the exception that will be bubbled up. Implementations however are not obligated to do such thing in which case they should return the same exception supplied. Notice however that:

The next interceptor in line will receive the exception returned by this method, which might not be the same one supplied in this invokation.

There's no guarantee that the exception returned by this method will be the one bubbled up, since the next interceptor in line might also change it.

Some interceptors might deal with the concept of retries. For example, an operation failing because of stale connection might attempt to reconnect and try again. For such interceptors, a retryRequest is provided so that a retry can be requested. The runtime is not obligated to grant such request and might decide to ignore it. Notice that the onError(OperationContext, RetryRequest, Throwable) and after(OperationContext, Object) method in all the other interceptors in line will be executed before the runtime decides to ignore/grant the retry request. If the petition is granted, then not only the operation will be re-executed. The whole interceptor chain (including the before(OperationContext) will also be executed again.

Implementations of this method should not fail. If they do throw any exception, it will be logged and ignored.

The after(OperationContext, Object) method is guaranteed to be executed regardless of this method's outcome in this or other involved instances

Parameters:

operationContext - the OperationContext that was used to execute the operation

retryRequest - a RetryRequest in case that the operation should be retried

exception - the Exception that was thrown by the failing operation

Returns:

the Exception that should be propagated forward

after

default void after(OperationContext operationContext,
                   Object result)

Executes after the execution of an operation is finished, regardless of it being successful or not.

In practical terms, it executes after the onSuccess(OperationContext, Object) or onError(OperationContext, RetryRequest, Throwable) but it doesn't execute if before(OperationContext) threw exception.

The result argument holds the return value of the operation. Because this method is invoked even if the operation failed, then the result will be a null in such a case. However, notice that testing result for being null is not an indicator of the operation having failed or not, since the operation might have successfully returned null. This method should be used for actions that should take place "no matter what". Actions that should depend on the operation's outcome are to be implemented using onSuccess(OperationContext, Object) or onError(OperationContext, RetryRequest, Throwable)

Parameters:

operationContext - the OperationContext that was used to execute the operation

result - the result of the operation. Can be null if the operation itself returned that or failed.