<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  ~  Copyright (c) 2009, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~  WSO2 Inc. licenses this file to you under the Apache License,
  ~  Version 2.0 (the "License"); you may not use this file except
  ~  in compliance with the License.
  ~  You may obtain a copy of the License at
  ~
  ~    http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<!DOCTYPE html
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
        <title>
            WSO2 ESB - Message Relay
        </title>
        <link href="css/esb-docs.css" rel="stylesheet"/>
        <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all"/>
    </head>
    <body xml:lang="en">
        [ <a href="docs_index.html"> Documentation Index </a> ]
        <h1>WSO2 Enterprise Service Bus (ESB) Message Relay</h1>
        <h2>Contents</h2>
        <div class="toc">
            <ol>
                <li>
                    <a href="#intro">Introduction</a>
                </li>
                <li>
                    <a href="#building_blocks">Message Relay Building blocks</a>
                </li>
                <li>
                    <a href="#config">Configuring the message relay</a>
                </li>
                <li>
                    <a href="#mediator">Builder mediator</a>
                </li>
                <li>
                    <a href="#module">Message Relay Module</a>
                </li>
                <li>
                    <a href="#policy">Message Relay Module Policy</a>
                </li>                
            </ol>
        </div>
        <h3 id="intro" >Introduction</h3>
        <p>
            Message Relay is a Message Pass through mechanism for ESB. Message relay enables ESB to pass the messages
            without building or processing the message.
        </p>
        <p>
            When message relay is configured incoming requests to the ESB are not built and processed unless
            specifically requested to do so. A incoming message is wrapped inside a default SOAP envelope as
            binary content and sent through the ESB.
        </p>
        <p>
            Some of the ESB scenarios doesn't require the full message to be built. Instead ESB can work on other
            message properties like request URLs or transport headers.
        </p>
        <p>
            With message relay ESB can achieve a very high throughput.
        </p>
        <hr/>
        <h3 id="building_blocks">
            Message Relay Building blocks
        </h3>
        <p>
            Message relay has two main parts.
        </p>
        <ul>
            <li>Axis2 Message Builder</li>
            <li>Axis2 Message Formatter</li>
        </ul>
        <p>A message builder is used to build an incoming message to the ESB. A message formatter is used to build the
            out going stream from the message inside ESB.</p>
        <p>
            So in a typical ESB routing scenario here is the flow
        </p>
        <p>
            Client &lt;---- Outgoing Message ----&gt; Message Formatter &lt;---- ESB &lt;---- Message Builder &lt;---- Incoming Message &lt;---- Service Provider
        </p>
        <p>
            Client &lt;---- Outgoing Message ----&gt; Message Formatter &lt;---- ESB &lt;---- Message Builder &lt;---- Incoming Message &lt;---- Service Provider
        </p>
        <p>
            When Relay Message builder and formatter are specified for a content type, message 
            coming with that content type will not be built by the ESB. Instead they will pass 
            through the ESB as it is.
        </p>
        <p>
            Message builders and formatters are specified in the axis2.xml under messageBuilders 
            and messageFormatters configuration section. Message builders and formatters are 
            chosen based on the content type of the message.
        </p>
        <p>
            ESB has few default Message message builders. Even if the user doesn't specify them 
            in the axis2.xml they will take effect. These can be overridden using the message 
            builder configurations in the axis2.xml.
        </p>
        <p> 
            ESB doesn't have default Message formatters. So it is important to specify all of 
            them in the axis2.xml configuration.
        </p>
        <p> 
          Here are the default message builders.
        </p>
        <table>
           <tr>
              <td>application/soap+xml</td>
              <td>org.apache.axis2.builder.SOAPBuilder</td>
           </tr>
           <tr>
              <td>multipart/related</td>
              <td>org.apache.axis2.builder.MIMEBuilder</td>
           </tr>
           <tr>
              <td>text/xml</td>
              <td>org.apache.axis2.builder.SOAPBuilder</td>
           </tr>
           <tr>
              <td>application/xop+xml</td>
              <td>org.apache.axis2.builder.MTOMBuilder</td>
           </tr>
           <tr>
              <td>application/xml</td>
              <td>org.apache.axis2.builder.ApplicationXMLBuilder</td>
           </tr>
           <tr>
              <td>application/x-www-form-urlencoded</td>
              <td>org.apache.axis2.builder.XFormURLEncodedBuilder</td>
           </tr>           
        </table>
        <h3 id="config">
            Configuring the message relay
        </h3>
        <p>In the axis2.xml file there are two configuration sections called messageBuilders and 
        messageFormatters. User can replace the expected content types with the relay message 
        builder and formattter to pass these messages through the ESB without building them.
        </p>
        <p>Message relay builder and formatter class names.</p>
        <pre xml:space="preserve">
        builder : org.wso2.carbon.relay.BinaryRelayBuilder
        formatter : org.wso2.carbon.relay.ExpandingMessageFormatter
        </pre>
        <p>Sample configuration for message relay</p>
        <pre xml:space="preserve">
	&lt;messageBuilders&gt;
        &lt;messageBuilder contentType=&quot;application/xml&quot;
                        class=&quot;org.wso2.carbon.relay.BinaryRelayBuilder&quot;/&gt;
        &lt;messageBuilder contentType=&quot;application/x-www-form-urlencoded&quot;
                        class=&quot;org.wso2.carbon.relay.BinaryRelayBuilder&quot;/&gt;
        &lt;messageBuilder contentType=&quot;multipart/form-data&quot;
                        class=&quot;org.wso2.carbon.relay.BinaryRelayBuilder&quot;/&gt;
        &lt;messageBuilder contentType=&quot;text/plain&quot;
                         class=&quot;org.wso2.carbon.relay.BinaryRelayBuilder&quot;/&gt;
        &lt;messageBuilder contentType=&quot;text/xml&quot;
                         class=&quot;org.wso2.carbon.relay.BinaryRelayBuilder&quot;/&gt;
    &lt;/messageBuilders&gt;        
        </pre> 
        <pre xml:space="preserve">
    &lt;messageFormatters&gt;
        &lt;messageFormatter contentType=&quot;application/x-www-form-urlencoded&quot;
                          class=&quot;org.wso2.carbon.relay.ExpandingMessageFormatter&quot;/&gt;
        &lt;messageFormatter contentType=&quot;multipart/form-data&quot;
                          class=&quot;org.wso2.carbon.relay.ExpandingMessageFormatter&quot;/&gt;
        &lt;messageFormatter contentType=&quot;application/xml&quot;
                          class=&quot;org.wso2.carbon.relay.ExpandingMessageFormatter&quot;/&gt;
        &lt;messageFormatter contentType=&quot;text/xml&quot;
                         class=&quot;org.wso2.carbon.relay.ExpandingMessageFormatter&quot;/&gt;
        &lt;!--&lt;messageFormatter contentType=&quot;text/plain&quot;
                         class=&quot;org.apache.axis2.format.PlainTextBuilder&quot;/&gt;--&gt;
        &lt;messageFormatter contentType=&quot;application/soap+xml&quot;
                         class=&quot;org.wso2.carbon.relay.ExpandingMessageFormatter&quot;/&gt;
    &lt;/messageFormatters&gt;
        </pre>
        <hr/>
        <h3 id="mediator">Builder mediator</h3>
        <p>Builder mediator can be used to build the actual SOAP message from a message coming in 
        to ESB through the message relay. One usage is to use this before trying to log the 
        actual message in case of a error. Also with the builder mediator ESB can be configured 
        to build some of the messages while passing the others along.</p>
        <p>Syntax of builder mediator</p>
        <pre>
    &lt;syn:builder xmlns:syn="http://ws.apache.org/ns/synapse"&gt;
        &lt;syn:messageBuilder contentType="" class="" [formatterClass=""]/&gt;
    &lt;/syn:builder&gt;
        </pre>
        <p>
        By default builder mediator uses the axis2 default message builders for the content types 
        specified in Table 1. User can override those by using the optional messageBuilder configuration.</p>
        <p>
        Like in axis2.xml user has to specify the content type and the implementation class of 
        the message builder. Also user can specify the message formatter for this content type. This is used by the
            ExpandingMessageFormatter to format the message before sending to the destination.
        </p>        
        <h3 id="module">Message Relay Module</h3>
        <p>Now message relay has a axis2 module as well. This is an optional feature. This module can be used 
        to build the actual SOAP message from the messages that went through the Message relay.</p>
        <p>
        To enable this module user has to enable the relay module globally in the axis2.xml</p>
        <pre>&lt;module ref=&quot;relay&quot;/&gt;</pre>
        <p>Also user has to put the following phase in to the InFlow of axis2.</p>
        <pre>&lt;phase name=&quot;BuildingPhase&quot;/&gt;</pre>
        <p>This module is designed to be used by Admin Services that runs inside the ESB. 
        All the admin services are running with content type: application/soap+xml. So if 
        a user wants to use admin console and use the ESB for receiving message with content 
        type application/soap+xml, this module should be used.
        </p><p> 
        User can configure the module by going to the modules section in admin console and then 
        going to the relay module. The module configuration is specified as a module policy. 
        After changing the policy user has to restart the ESB for changes to take effect.</p>
        <h3 id="policy">Message Relay Module Policy</h3>
        <pre xml:space="preserve">
&lt;wsp:Policy wsu:Id=&quot;MessageRelayPolicy&quot; xmlns:wsp=&quot;http://schemas.xmlsoap.org/ws/2004/09/policy&quot;
                xmlns:wsmr=&quot;http://www.wso2.org/ns/2010/01/carbon/message-relay&quot;
                xmlns:wsu=&quot;http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&quot;&gt;
        &lt;wsmr:RelayAssertion&gt;
            &lt;wsp:Policy&gt;
                &lt;wsp:All&gt;
                    &lt;wsmr:includeHiddenServices&gt;false | false&lt;/wsmr:includeHiddenServices&gt;
                    &lt;wsmr:services&gt;
                        &lt;wsmr:service&gt;Name of the service&lt;/wsmr:service&gt;*
                    &lt;/wsmr:services&gt;
                    &lt;wsmr:builders&gt;
                        &lt;wsmr:messageBuilder contentType=&quot;content type of the message&quot; class=&quot;message builder implementation class&quot; class=&quot;message formatter implementation class&quot;/&gt;
                    &lt;/wsmr:builders&gt;
                &lt;/wsp:All&gt;
            &lt;/wsp:Policy&gt;
        &lt;/wsmr:RelayAssertion&gt;
&lt;/wsp:Policy&gt;
        </pre>
        <p>
        These are the assestions:</p>
        <p>
			includeHiddenServices: If this is true message going to the services with hiddenService parameter will be built</p>
			<p>wsmr:services: Messages going to these services will be built</p>
			<p>wsmr:service: Name of the service</p>

			<p>wsmr:builders: Message builders to be used for building the message</p>
			<p>wsmr:builder: A message builder to be used for a content type</p>

			<h3>Message Relay Limitations</h3>
			<p>
				If the message relay is enabled for particular content type, there cannot be Services with 
				security enabled for that content type. This applies to services with reliable messaging as well.
            </p>              
    </body>
</html>
