Best Practices for Mediation

This section explains the best practices to be followed when creating mediation sequences in the following scenarios.

General best practices

Following are some general best practices that you can follow when working with mediators.

• Use Iterator mediator in association with Aggregate mediator.

• Do not do any configuration after the Send mediator.

• Do proper error handling to handle mediation errors as well as endpoint errors.

• Use dollar context (i.e. $ctx)instead of using the get property.

  This is because the get-property methods search even in Registry if the value is not available in the message context. Thus, it affects performance as Registry search is an expensive operation. However, $ctx only checks in the message context. 

• Use appropriate intervals for tasks.

• Use the ForEach mediator only for message transformations. If you need to make back-end calls from each iteration, then use the iterate mediator.

Last mediator in a sequence

The last mediator in a mediation sequence should be one of the following mediators depending on the scenario. Any mediator added after one of the following mediators will not be applied.

• Drop mediator: when you want to stop the mediation flow at a particular point (e.g., when a filter condition is not met).
• Loopback mediator: when you want the message to be moved from the In sequence to the Out sequence. Note that the Loopback mediator only prevents the subsequent mediators in the In sequence from being applied.
• Respond mediator: when you want the message to be sent back to the client. 
• Send Mediator: when you want the message to be sent to the specified endpoint. If a message should be further mediated after it is sent, you can use the Clone mediator to make two copies of the message and process them separately, thereby avoiding conflicts.

Defining the In and Out sequences

The In and Out sequences are separately defined for proxy services and REST APIs. Therefore, In and Out mediators should not be used in proxy service and REST API configurations. However, they should be used in the main sequence.

The correct usage of the Loopback mediator

Once a message has been passed from the In sequence (request path) to the Out sequence (response path), it cannot be moved to the Out sequence again via the Loopback mediator.

Reusing a defined sequence

In order to repeatedly use the same mediation sequence, you can define it and save it in the Synapse configuration or the Registry with a unique name as described in Adding a Mediation Sequence. This mediation sequence can then be called from the main sequence as well as multiple proxy services and REST APIs. The saved sequence can be called via the Sequence mediator or selected as the In/Out/Fault sequence when defining a proxy service or a REST API.

The correct usage of the Sequence mediator

The Sequence mediator calls a Mediation Sequence saved in the Synapse configuration or the Registry with a unique name. The In, Out or Fault sequence of a proxy service, REST API or the Main sequence cannot be called via this mediator.

The correct usage of the ForEach mediator

Iterate Mediator is quite similar to the ForEach mediator. You can use complex XPath expressions to conditionally select elements to iterate over in both mediators. Following are the main difference between ForEach and Iterate mediators:

• Use the ForEach mediator only for message transformations. If you need to make back-end calls from each iteration, then use the iterate mediator.
• ForEach supports modifying the original payload. You can use Iterate for situations where you send the split messages to a target and collect them by an Aggregate in a different flow
• You need to always accompany an Iterate with an Aggregate mediator. ForEach loops over the sub-messages and merges them back to the same parent element of the message.
• In Iterate you need to send the split messages to an endpoint to continue the message flow. However, ForEach does not allow using Call, Send and Callout mediators in the sequence.
• ForEach does not split the message flow, unlike Iterate Mediator. It guarantees to execute in the same thread until all iterations are complete.

When you use ForEach mediator, you can only loop through segments of the message and do changes to a particular segment. For example, you can change the payload using payload factory mediator. But you cannot send the split message out to a service. Once you exit from the ForEach loop, it automatically aggregates the split segments. This replaces the ForEach function of the complex XSLT mediators using a ForEach mediator and a Payload Factory mediator. However, to implement the split-aggregate pattern, you still need to use Iterate mediator.

The correct usage of the Clone mediator

When using a Clone mediator, use a Call mediator in the target sequence to bring the responses back into the In-Sequence. This continues the mediation since the Continuation Stack gets pushed into the Synapse Message Context via the handleMessage method in the SynapseCallbackReceiver class.

Otherwise, the Continuation Stack becomes empty in the Synapse Message Context if you do not use a Call mediator in the target sequence.