Callout Mediator
- Former user (Deleted)
The Callout mediator performs a blocking external service invocation during mediation.
As the Callout mediator performs a blocking call, it cannot use the default non-blocking HTTP/S transports based on Java NIO. Instead, it defaults to using <EI_HOME>/conf/axis2/axis2_blocking_client.xml as the Axis2 configuration, and <EI_HOME>/repository/deployment/client as the client repository unless these are specified separately.
The Call mediator leverages the non-blocking transports for much greater performance than the Callout mediator, so you should use the Call mediator in most cases. However, the Callout mediator is recommended in situations where you need to execute the mediation flow in a single thread.
Setup
Enabling mutual SSL
Since the Callout mediator is run based on the configuration of the axis2_blocking_client.xml file, its default https transport sender is org.apache.axis2.transport.http.CommonsHTTPTransportSender. Therefore, the Callout mediator does not have access to the required key store to handle mutual SSL. To enable the Callout mediator to handle mutual SSL, the following JVM settings should be added to the <EI_HOME>/bin/integrator.sh file.
-Djavax.net.ssl.keyStore="$CARBON_HOME/repository/resources/security/wso2carbon.jks" \ -Djavax.net.ssl.keyStorePassword="wso2carbon" \ -Djavax.net.ssl.keyPassword="wso2carbon" \
Disabling chunking
The Callout mediator is not affected by the DISABLE_CHUNKING property. Instead, you can disable chunking for the Callout mediator by setting the Transfer-Encoding parameter to none in CommonsHTTPTransportSender of axis2_blocking_client.xml as follows:
<parameter name="Transfer-Encoding">none</parameter>
For example:
<transportSender name="http"
class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
<parameter name="PROTOCOL">HTTP/1.1</parameter>
<parameter name="Transfer-Encoding">none</parameter>
<parameter name="cacheHttpClient">true</parameter>
<parameter name="defaultMaxConnectionsPerHost">200</parameter>
</transportSender>
This will disable chunking for all Callout mediators present in the EI server.
If you want to disable chunking for only a single Callout mediator instance, create a new axis2.xml file by copying the axis2_blocking_client.xml file, set the Transfer-Encoding parameter as shown, and then configure that Callout mediator to use this new axis2.xml file as described below.
Syntax
<callout [serviceURL="string"] [action="string"] [initAxis2ClientOptions="true|false"] [endpointKey="string"]>
<configuration [axis2xml="string"] [repository="string"]/>?
<source xpath="expression" | key="string" | type="envelope"/>
<target xpath="expression" | key="string"/>
<enableSec policy="string" | outboundPolicy="String" | inboundPolicy="String" />?
</callout>
Configuration
There will be a slight difference in the UI depending on the option you select for the Specify as parameter. Click on the relevant tab to view the required UI.
The parameters available for configuring the Callout mediator are as follows.
| Parameter Name | Description |
|---|---|
| Specify As | This parameter determines whether the target external service should be configured by using either a Callout mediator does not support endpoint configurations such as
If neither a URL or an address endpoint is specified, the |
| URL | If you selected URL for the Specify As parameter, use this parameter to enter the URL of the external service that you want to call. This URL will be used as the End Point Reference (EPR) of the external service. |
| Address Endpoint | If you selected Address Endpoint for the Specify As parameter, use this parameter to enter key to access the endpoint that should be used to call the external service. Click Configuration Registry or Governance Registry as relevant to select the required endpoint from the resource tree. |
| Action | The SOAP action which should be appended to the service call. |
| Axis2 Repository | The path to Axis2 client repository where the services and modules are located. The purpose of this parameter is to make the Callout mediator initialize with the required client repository. |
| Axis2 XML | The path to the location of the Axis2.xml configuration file. The purpose of this parameter is to make the Callout mediator initialize with the relevant Axis2 configurations. |
| initAxis2ClientOptions | If this parameter is set to false, the existing Axis2 client options available in the Synapse message context will be reused when the Callout mediator is invoked. This is useful when you want to use NLTM authentication. The default value for this parameter is true. |
| Source | This parameter defines the payload for the request. It can be defined using one of the following options.
|
| Target | The node or the property of the request message to which the payload (resulting from the value specified for the Source parameter) would be attached. The target can be specified using one of the following options.
|
| WS-Security | If you select the check box, WS-Security is enabled for the Callout mediator. This section would expand as shown below when you select this check box. |
| Specify as Inbound and Outbound Policies | If this check box is selected, you can define separate security policies for the inbound and outbound messages (flows). This is done by entering the required policy keys in the Outbound Policy Key and Inbound Policy Key parameters which are displayed as follows when this check box is selected. You can click Configuration Registry or Governance Registry to select a security policy saved in the Registry from the resource tree. |
| Policy Key | If the Specify as Inbound and Outbound Policies check box is not selected, this parameter is used to enter a key to access a security policy which will be applied to both inbound and outbound messages. You can click Configuration Registry or Governance Registry to select a security policy saved in the Registry from the resource tree. |
Examples
Following examples demonstrate the usage of the Callout mediator.
Example 1 - Performing a direct service invocation
In this example, the Callout Mediator does the direct service invocation to the StockQuoteService using the client request, gets the response, and sets the response as the first child of the SOAP message body. You can then use the Send Mediator to send the message back to the client.
<callout serviceURL="http://localhost:9000/services/SimpleStockQuoteService"
action="urn:getQuote">
<source xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:s12="http://www.w3.org/2003/05/soap-envelope"
xpath="s11:Body/child::*[fn:position()=1] | s12:Body/child::*[fn:position()=1]"/>
<target xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:s12="http://www.w3.org/2003/05/soap-envelope"
xpath="s11:Body/child::*[fn:position()=1] | s12:Body/child::*[fn:position()=1]"/>
</callout>
Example 2 - Setting an HTTP method when invoking a REST service
The below example uses a C allout mediator to set a HTTP method when invoking a REST service.
For this, you need to define the following property: <property name="HTTP_METHOD" expression="$axis2:HTTP_METHOD" scope="axis2-client"/>
<proxy xmlns="http://ws.apache.org/ns/synapse"
name="CalloutProxy"
startOnLoad="true"
statistics="disable"
trace="disable"
transports="http,https">
<target>
<inSequence>
<property name="enableREST"
scope="axis2-client"
type="BOOLEAN"
value="true"/>
<property expression="$axis2:HTTP_METHOD"
name="HTTP_METHOD"
scope="axis2-client"/>
<callout initAxis2ClientOptions="false"
serviceURL="http://localhost:8280/callout/CalloutRESTApi">
<source type="envelope"/>
<target key="response"/>
</callout>
<log level="custom">
<property expression="$ctx:response" name="MESSAGE###########################3"/>
</log>
<property expression="$ctx:response" name="res" type="OM"/>
<property action="remove" name="NO_ENTITY_BODY" scope="axis2"/>
<property name="RESPONSE" value="true"/>
<property name="messageType" scope="axis2" value="application/xml"/>
<header action="remove" name="To"/>
<payloadFactory media-type="xml">
<format>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>$1
</soapenv:Body>
</soapenv:Envelope>
</format>
<args>
<arg evaluator="xml" expression="$ctx:res"/>
</args>
</payloadFactory>
<send/>
</inSequence>
</target>
<description/>
</proxy>