Send Mediator

The Send Mediator is used to send messages out of Synapse to some endpoint. The Send Mediator also copies any message context properties from the current message context to the reply message received on the execution of the send operation, so that the response could be correlated back to the request. Messages may be correlated by WS-A MessageID, or even simple custom text labels.

There are two modes of operation in a Send Mediator:

Sending a message using message-level information
Sending a message to a predefined endpoint

If we do not provide an endpoint, it will try to send the message using the wsa:to address of the message. Also, if we use the Send mediator in the out path of the ESB without specifying an endpoint, it will send the message as a reply. If we do provide an endpoint, it will send the message according to the information in the endpoint. The endpoint type can be either a Leaf endpoint (i.e. Address, WSDL, Default or Http) or a Group endpoint (Failover, Loadbalance or Recipient List).

The Send Mediator copies any message context properties from the current message context to the reply message received on the execution of the send operation so that the response can be correlated back to the request. Messages may be correlated by WS-A Message-ID, or even simple custom text labels.

A send operation can be blocking or non-blocking depending on the actual transport implementation used. As the default NIO-based http/s implementation does not block on a send, care must be taken if the same message must be sent and then further processed (e.g., transformed). In such a scenario, it may be first required to clone the message into two copies and then perform processing to avoid conflicts.

Syntax

<send/>

If the message is to be sent to one or more endpoints, use the following syntax:

<send>
   (endpointref | endpoint)+
</send>

The endpointref token refers to the following:

<endpoint key="name"/>

The endpoint token refers to an anonymous endpoint definition.

Specifying a response-handling sequence (service chaining)

You can also specify the sequence you want to use for handling responses to the request if you don't want to use the default out sequence. For example:

<send receive="personInfoSeq">
    <endpoint key="PersonInfoEpr"/>
</send>

In this example, requests are sent to the PersonInfoEpr endpoint, and responses from the service at that endpoint are handled by a sequence named personInfoSeq. This approach is particularly useful for service chaining. For example, let's assume you want to take the responses from the PersonInfoEpr service and send them to the CreditEpr service for additional processing before sending the final response back to the client. In this case, you would configure the personInfoSeq sequence to send the response to the CreditEpr service and also specify another receive sequence (creditSeq) that sends the response from the CreditEpr service back to the client. Following is the configuration of these sequences:

<sequence name="personInfoSeq">
    <xslt key="xslt">
        <property name="amount" expression="get-property('ORG_AMOUNT')"/>
    </xslt>
    <send receive="creditSeq">
        <endpoint key="CreditEpr"/>
    </send>
</sequence>

<sequence name="creditSeq">
    <log level="full"/>
    <send/>
</sequence>

UI Configuration

You can select the endpoint to be one of the following values:

None
Define Inline Allows you to define and add the endpoint in one step. Click Add, choose an endpoint type from the list, and then define it as described in Adding an Endpoint.
Pick From Registry - Pick a path either from Configuration Registry or Governance Registry. See Working with the Registry for more information about choosing a path from the registry.
XPath - Allows to choose XPath from the Namespaces or to add a new one.
Receiving Sequence Type - The sequence to use for handling the response from the endpoint. The default is the out sequence defined in the proxy service. You can specify a different sequence by specifying a static value, or it can be calculated using an XPath.

Build Message Before Sending - When set to No, this setting improves performance by not building the full message XML in memory before sending it. If your configuration includes logic that is performed after the Send has initiated, set this option to Yes.

Examples

Example 1 - Send mediator used in the In sequence and Out sequence

In this example, the first send operation is included in the In mediator. Both the request and response will go through the main sequence, but only request messages will go through the In mediator. Similarly, only response messages will go through the Out mediator. The request will be forwarded to the endpoint with the given address. The response will go through the second send operation, which in this example just sends it back to the client because there is no Out endpoint specified.

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <in>
        <send>
            <endpoint>
                <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
            </endpoint>
        </send>
        <drop/>
    </in>
    <out>
        <send/>
    </out>
</definitions>

Example 2 - Specifying a response handling sequence (service chaining)

<send receive="personInfoSeq">
    <endpoint key="PersonInfoEpr"/>
</send>

In this example, requests are sent to the PersonInfoEpr endpoint, and responses from the service at that endpoint are handled by a sequence named personInfoSeq. This approach is particularly useful for service chaining. For example, if you want to take the responses from the PersonInfoEpr service and send them to the CreditEpr service for additional processing before sending the final response back to the client. In this case, you can configure the personInfoSeq sequence to send the response to the CreditEpr service and also specify another receive sequence named creditSeq that sends the response from the CreditEpr service back to the client. Following is the configuration of these sequences.

<sequence name="personInfoSeq">
    <xslt key="xslt">
        <property name="amount" expression="get-property('ORG_AMOUNT')"/>
    </xslt>
    <send receive="creditSeq">
        <endpoint key="CreditEpr"/>
    </send>
</sequence>

<sequence name="creditSeq">
    <log level="full"/>
    <send/>
</sequence>

Example 3 - Configuring a blocking/non-blocking send operation

In this example, the Send mediator in a proxy service using the VFS transport is transferring a file to a VFS endpoint. VFS is a non-blocking transport by default, which means a new thread is spawned for each outgoing message. The Property mediator added before the Send mediator removes the ClientAPINonBlocking property from the message to perform the mediation in a single thread. This is required when the file being transferred is large and you want to avoid out-of-memory failures.

<inSequence>
   <property name="ClientApiNonBlocking"
           value="true"
           scope="axis2"
           action="remove"/>
   <send>
      <endpoint name="FileEpr">
         <address uri="vfs:file:////home/shammi/file-out"/>
      </endpoint>
   </send>
</inSequence>