Binary-Relay: An Efficient way to pass both XML and non-XML content through Apache Synapse

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Srinath Perera
  • 15 Dec, 2009


For example, with this extension in place, we can send poorly formed html through Apache Synapse, which is very useful for load balancing and high-availability purposes. Moreover, load balancing scenarios often operate solely on transport headers, and in those cases, this extension allows Apache Synapse to process those messages without processing content of the messages, which could yield significant performance gains.

We use the term Binary-Relay to describe this behavior based on the notion that this extension enables Apache Synapse to relay messages to a different party efficiently at byte level while making decisions using transport headers. Binary-Relay can be selectively enabled for different content types. For instance, you may enable Relay only for text/html and let the other content types ( e.g. text/ xml) to be processed as usual.

This article introduces Binary-Relay. To that end, we shall describe the motivation, the architecture, and use cases of Binary-Relay. Moreover, we shall present a preliminarily performance study, which demonstrates its effectiveness.


Relay support is motivated by an apparent gap in load balancing and high availability technologies when they are used with SOA based projects. Let us consider an example.

WSO2 Governance Registry enables users to store, retrieve, and manage information through several APIs, and among them, the browser based HTML User Interface is a major component. For high availability and scalability, often WSO2 Governance Registry is deployed in a cluster, which is fronted by a load balancing component like WSO2 Enterprise Service Bus(WSO2 ESB). However, in this juncture, we face a problem. Since WSO2 Governance Registry has to support SOAP requests as well as HTML requests, the load balancer needs to be able to handle both SOAP content as well as non-SOAP content. On this setting, conventional SOAP based Load balancers will complain about non-well formed content in HTML messages, and moreover, even with well formed messages, they will parse those messages in spite of the fact that the information in their payload is never used for load balancing decisions, hence wasting computing power needlessly. It is possible to handle this scenario by carefully setting up a HTML based load balancer ( e.g.. Apache mod_proxy) and a SOAP based load balancer, and then routing each type of traffic through the corresponding load balancer. However, in contrast, Relay support enables users to use Apache Synapse to handle both the traffic via few configuration changes while also gaining performance in the process. A similar problem also arises in high-availability scenarios and Binary-Relay shall also be applied in that situation as well.

Though we used WSO2 Governance Registry as an example, this problem is common to most WSO2 products. Moreover, in real life settings, the need to send both XML and non-XML content through the same front-end often arises. Binary-Relay solves this problem by giving the choice of handling a subset of requests at the byte level to the end user, thus enabling both XML and non-XML content to co-exist and also provides performance gains in the process.

To summarize, Binary-Relay is meant to solve two problems.

  1. It enables Apache Synapse to load balance both non-well formed HTTP as well as SOAP traffic in the same time, thus avoiding the need for two load balancers and painful configurations.
  2. Even for SOAP messages, if Apache Synapse routing logic does not read content of messages and only operates on transport level information, Binary-Relay enables Apache Synapse to pass them through without performing heavy XML parsing.

In the next section, we will be discussing how the above requirements will be realized.

Architecture: How does it work?

Apache Axis2, which is the base for Apache Synpase's SOAP processing, helps users to add their custom message formats through Builders and Formatters. A Builder accepts a binary data stream and creates an XML message, and a Formatter accepts a XML message and converts it to bytes. Users may define their own Formatters and Builders and registers them against specific content types, and Apache Axis2 will use those Formatters and Builders to process messages belonging to corresponding content types. For example, when Apache Axis2 received a message, it looks up the Builder registered for the content type of the message, and asks it to build an XML message from the request message provided as bytes. On the other hand, when sending a message out ( e.g., At the end of the processing pipeline), Apache Axis2 looks up the Formatter registered for target content type, and asks the Formatter to convert XML messages to bytes. Consequently, the kernel of Apache Axis2 is not aware of any specific format, but operates on XML messages.

Binary-Relay uses these Formatters and Builders to relay messages---both well formed as well as ill-formed messages---through Apache Synapse without processing ( e.g. . XML Validation or processing) those messages. Binary-Relay includes a Builder and a Formatter. When a message is received, the Builder creates a fake SOAP message, attaches the content of the incoming SOAP message as a binary XML node, and sends it through the Apache Axis2 kernel, and when it is being sent out, the Binary-Relay Formatter expands the SOAP messages and writes the attached content to the output channel. Consequently, the message goes through Apache Synapse without processing its content, since the message is handled at the bytes level, even non-XML messages may go through Apache Synapse. It is worth noting that the SOAP message that goes through Apache Axis2 engine has a non-standard content and format. Hence, if someone wants to access the real message contained in the fake SOAP message, he has to explicitly know that this is a wrapped message and has to expand it himself. However, in the above scenarios we discussed, all the decisions are taken based on transport headers ( e.g., HTTP headers), and wrapped SOAP message, therefore, does not impose any problems.

With the above architecture, Binary-Relay can be tuned on and off based on content type, but often users need more fine-grained control. For example, they might need to turn this on and off per service basis. To support that, we have added a new handler to the Apache Axis2 pipeline, through which users can define specific services for which Binary-Relay needs to be tuned on as a configuration parameter. When Binary-Relay is set up, every message is first wrapped and processed until its target service has been determined. The Handler lets messages for services that have Binary relay enabled to go forward as wrapped messages, and for other messages, handler unwrap the wrapped SOAP message and pass it on as a normal SOAP message. Unlike filtering based on content types, this method incurs an overhead; however, unless the message is very large, this overhead should not be prohibitive.

Setting up Binary-Relay

Setting up Binary-Relay is a straight forward process, and the following instructions describe how to enable it in Apache Synapse and WSO2 Enterprise Service Bus (WSO2 ESB).

  1. Build the code by typing the mvn clean install in the checkout directory, a jar will be created with the target directory.
  2. For Apache Synapse, copy the jar in to lib folder and for WSO2 Enterprise Service Bus, copy it to repository/component/lib folder.
  3. Restart WSO2 Enterprise Service Bus for Apache Synapse.
  4. The add following message builders and formatters to the corresponding sections in conf/axis2.xml (for both Apache Synapse and WSO2 Enterprise Service Bus).
<messageBuilder contentType="text/html"
<messageFormatter contentType="text/html"

The above example shows how to enable Binary Relay for text/html content type. You need to repeat the above pair of configurations for each content type you want to be handled at the byte level. Furthermore, you may have to remove some existing entries if they are also registered with same content type for which you will enable Builders and Formatters.

The above configurations only enables a user to turn Binary-Relay on and off for different content types. If you need to turn it on and off for services, you should also add the following Handler into inflow handler Chain of Apache Axis2 (see Apache Axis2 Execution Framework for details), and you can define names of services for which Binary-Relay should be disabled as a list ( e.g., A,B,C).

<handler name="SkipAdminServiceHandler"  class="org.wso2.carbon.relay.SkipAdminServiceHandler">
	<parameter name="excludedServiceList" value="A,B,C"/>

Performance Results

We have performed the following experiment to evaluate the performance gain induced by Binary-Relay.

To that end, we have setup a WSO2 Enterprise Service Bus to mediate requests to a service while only reading HTTP headers, and as the service, we have used Mesh operation used by Apache Axis2 Performance tests done earlier[1] with WS-Security, both Signature and Encryption. Each request and response was of the size about 150KB. To ensure that bottleneck in the setup is not induced by the backend service, as the service implementation, we have used a Servelt, which returns a pre-cooked response whenever it receives a request. Moreover, to generate load, we used the java clone of Apache bench described in the article WSO2 Enterprise Service Bus Performance Testing Round 1. To run the client, WSO2 Enterprise Service Bus, and the backend, we have used three Intel(R) Xeon(TM) 3.20GHz 2MB Cache Dual Core - 2 CPU system / 2GB RAM / 1G NW machines. The results are depicted in the following table.

With Optimization ([#/sec] (mean)) Without Optimization ([#/sec] (mean))
Requests per second 158.40 65.01
Time per request 252.529 615.294

These results suggest that using Binary-Relay could provide around 3X boost on throughput and about 2.5 boost on response time on the tested use case. Moreover, in a real world deployment, we have seen Binary-Relay processing in excess of 1500 requests for second while keeping very low resource utilization. We agree that the above results are not conclusive, and we need further study to understand the capacity of Binary-Relay. Nevertheless, we believe above results provide a glimpse if its possibilities.


This article introduces Binary-Relay and its architecture. Furthermore, it demonstrated it from a User perspective describing how to install and enable Binary-Relay within the user's setup. Finally, we present some initial results, which shows that Binary-Relay can provide up to 3X performance boost in contrast to conventional setup.

So far, we have seen two major applications of Binary-Relay: first, as a way to route both XML and non-XML content through the same Load Balancer while making application level decisions, and the second, as a replacement for HTTP load balancer. It is worth noting that we do not see it as a replacement for HTTP load balancers ( e.g. apache mod_proxy) in general sense, rather some special circumstances at deployment setup permit such applications. For an example, some environments decapitate that the deployment must have only one type of load balancer, and in such settings, Binary-Relay is an attractive solution when users need HTTP load balancer in their SOA deployment together with application level load balancing. Moreover, users have chosen Apache Synapse with Binary-Relay to take advantage of comprehensive mediation language and scripting languages available through Apache Synapse against more conventional HTTP load balancers. In conclusion, we believe Binary-Relay is a very useful tool in solution Architect's arsenal.


  1. Web Services are Not Slow
  2. Asankha Perera, WSO2 ESB Performance Testing Round 1
  3. Deepal Jayasinghe , Apache Axis2 Execution Framework


Srinath Perera, Software Architect, WSO2, srinath AT wso2 DOT com


About Author

  • Srinath Perera
  • Vice President, Research
  • WSO2 Inc.