How to setup binary relay in WSO2 ESB-3.0.0

The latest version of WSO2 ESB will be out by few days and the final set of release candidate builds are currently going through the test process. WSO2 ESB-3.0.0 consists of a set of new features as well as enhancements to the existing features. Binary relay feature has been included since the previous ESB release (WSO2 ESB-2.1.3) however many bug fixes and enhancements are included in the new release.

Binary relay allow users to send messages to a different party efficiently at byte level while making decisions using transport headers. It enables ESB to pass through SOAP messages without performing heavy XML parsing. You can find more information about the architectural details of binary relay in this article written by Dr. Srinath Perera.

I'm going to demonstrate the steps to configure binary relay in WSO2 ESB-3.0

Pre-requisites:

Download WSO2 ESB-3.0.0 from here (I'm using the latest release candidate which can be downloaded from here)

Step 1

First we must enable the relay module in the ESB management console so that it unwraps the messages received by the admin services.

Log in to management console and go to Manage --> Modules --> List and click on engage icon associated with relay module to engage the module globally.

Step 2

Now, we should configure the necessary message formatters and builders in axis2.xml configuration file.

Go to ESB_HOME/repository/conf/axis2.xml and locate the messageFormatters and messageBuilders section.

Uncomment the relay message formatters and builders as follows. Also, comment out the other (default) formatters and builders.

<messageFormatters>

<!--<messageFormatter contentType="application/x-www-form-urlencoded"

class="org.apache.axis2.transport.http.XFormURLEncodedFormatter"/>

<messageFormatter contentType="multipart/form-data"

class="org.apache.axis2.transport.http.MultipartFormDataFormatter"/>

<messageFormatter contentType="application/xml"

class="org.apache.axis2.transport.http.ApplicationXMLFormatter"/>

<messageFormatter contentType="text/xml"

class="org.apache.axis2.transport.http.SOAPMessageFormatter"/>

<messageFormatter contentType="application/soap+xml"

class="org.apache.axis2.transport.http.SOAPMessageFormatter"/>-->

<messageFormatter contentType="application/x-www-form-urlencoded"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

<messageFormatter contentType="multipart/form-data"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

<messageFormatter contentType="application/xml"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

<messageFormatter contentType="text/html"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

<messageFormatter contentType="application/soap+xml"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

<messageFormatter contentType="text/xml"

class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>

<!--messageFormatter contentType="x-application/hessian"

class="org.apache.synapse.format.hessian.HessianMessageFormatter"/-->

<!--messageFormatter contentType=""

class="org.apache.synapse.format.hessian.HessianMessageFormatter"/-->

<!--

class="org.apache.axis2.format.PlainTextFormatter"/>-->

</messageFormatters>

<messageBuilders>

<!-- <messageBuilder contentType="application/xml"

class="org.apache.axis2.builder.ApplicationXMLBuilder"/>

<messageBuilder contentType="application/x-www-form-urlencoded"

class="org.apache.axis2.builder.XFormURLEncodedBuilder"/>

<messageBuilder contentType="multipart/form-data"

class="org.apache.axis2.builder.MultipartFormDataBuilder"/>-->

<messageBuilder contentType="application/xml"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

<messageBuilder contentType="application/x-www-form-urlencoded"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

<messageBuilder contentType="multipart/form-data"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

<messageBuilder contentType="application/soap+xml"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

<messageBuilder contentType="text/plain"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

<messageBuilder contentType="text/xml"

class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

<!--messageBuilder contentType="x-application/hessian"

class="org.apache.synapse.format.hessian.HessianMessageBuilder"/-->

<!--messageBuilder contentType=""

class="org.apache.synapse.format.hessian.HessianMessageBuilder"/-->

<!-- <messageBuilder contentType="text/plain"

class="org.apache.axis2.format.PlainTextBuilder"/>-->

</messageBuilders>

Save axis2.xml file and restart the server. Now, the server will be running with binary relay enabled.

Step 3

In order to verify how message mediation happens with binary relay, create a simple pass through sequence and send few SOAP requests. If you enable DEBUG level logging for org.apache.synapse, you will notice the message with binary content as follows.

<ns:binary xmlns:ns="http://ws.apache.org/commons/ns/payload">PD94bWwgdmVyc2lvbj0nMS4wJyB

lbmNvZGluZz0nVVRGLTgnPz48c29hc</ns:binary>