Send mediator are used extensively in mediation sequences in the WSO2 ESB. Without a Send mediator of course, little will happen in either the IN sequence (the Send mediator sends it to the endpoint you defined) or the OUT sequence (the Send mediator sends the message back to the client.
Time to take a look at this mediator that we use often but perhaps no little about. At the end of the blog we also take a look at other mediator that are related to the Send mediator, like Call, Respond and Drop.
How does Send mediator work?
In its simplest form it sends the message to the defined endpoint. This endpoint can be defined inline (hardcoded), be a predefined endpoint (named or in a registry) or can be derived from an XPATH expression. If no endpoint is defined, the Send will try and send the message to the TO header.
If the Send mediator is in the OUT sequence it will simply just send it to the client if no endpoint is defined. Defining an endpoint in the Send mediator in the OUT sequence will send it to that endpoint.
The syntax of the Send mediator is quite simple:
If there is a endpoint included in the Send the syntax looks like this:
We will see a little bit later on what parameters are possible because although the syntax seems straightforward it does allow for more than you think.
The Endpoint in the Send mediator can be:
- Empty (see previous paragraph for the flow)
- Defined inline (hardcoded in the send mediator)
- Picked from registry or other named endpoint
- XPath Statement
According to the documentation, you can also send a message to multiple endpoints.
An example of a Send mediator with an endpoint defined inline
An example with both a defined Endpoint and a named OUT sequence
When you want to work with multiple endpoints you need to define them in a recipientlist. For more information, there is a Enterpise Integration Pattern (EIP) sample in the documentation. A recipientlist would look something like this:
Another possibility is to define the receiving Sequence type for the Send. By this we mean the OUT sequence (if no receiving endpoint is specified it will take the default endpoint in the proxy or API or a static (named sequence) or even dynamic endpoint. In the latter case an XPath Statement should be provided.
The final parameter is to specify if the message is built in memory before sending. If there is logic that needs to take place after the send this parameter needs to be set to Yes. Otherwise leave it to No, which improves the performance.
The Send mediator can be defined using the UI of the WSO2 ESB, Developer Studio or as an XML snippet that is copied into a proxy or API.
It is important to realize that the Send Mediator will leave the current flow (IN or OUT). Placing any mediators after Send will not work since they will never be reached.
The Call Mediator does something similar to the Send mediator but unlike the Send mediator, stays within the flow of the proxy or API. This allows for service chaining, a number of consecutive calls where for instance results are handed over from one call to another using properties that are set.
The Call mediator syntax resembles the Send Mediator Syntax
(endpointref | endpoint)+
In this cases multiple endpoints are supported, however only in non blocking mode.
Figure 1 Example from the ESB fundamentals training where in the OUT sequence another service is called
In theory, there are more ways to to service chaining by using IN and OUT flows of a named sequence or even a construction where in the OUT flow of for instance a proxy a switch and another send are used (the switch determines if there is another call that needs to be made) but this is really suboptimal. The Call mediator is the way to do service chaining within the WSO2 ESB.
Another content unaware mediator that is related to the send mediator is the Drop mediator that does exactly the opposite of the Send mediator: it drops the message. If the the Drop Mediator is placed in the IN Sequence it will give a 202 Accepted response to the client. If placed in the out sequence it does not give back a response but simply drops the message.
It’s syntax is the simplest of all :
The Respond mediator sends back the message to the client and stops current processing. One of the uses is with Makefault Mediator to give a soap message back to the client that there is something wrong with the message (e.g. the payload is not correct or something).
In this case the syntax is also simple:
One of the least know mediators is the loopback mediator. As you can see in the image below, the loopback mediator transfers the flow to the out sequence where the variables on the axis2 scope are maintained.
The syntax is :
When would you use the loopback? Well, basically when you want to use the outsequence to format the response to the client.
In this overview we have looked at some of the possibilities to manage the flow within a proxy, like sending it to different endpoints, invoking named outsequence and so on. Now you know that you have an option to change the flow that might be very handy for one of your own projects.
If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
|WSO2TORIALS help you to change, update or improve WSO2 products and are based on our experiences with the products. WSO2TORIALS will guide you step by step with minimal knowledge required.|