<?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 EI - Message Relay
        </title>
        <link href="css/EI-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 Integrator (EI) 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 EI. Message relay enables EI to pass the messages
            without building or processing the message.
        </p>
        <p>
            When message relay is configured incoming requests to the EI 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 EI.
        </p>
        <p>
            Some of the EI scenarios doesn't require the full message to be built. Instead EI can work on other
            message properties like request URLs or transport headers.
        </p>
        <p>
            With message relay EI 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 EI. A message formatter is used to build the
            out going stream from the message inside EI.</p>
        <p>
            So in a typical EI routing scenario here is the flow
        </p>
        <p>
            Client &lt;---- Outgoing Message ----&gt; Message Formatter &lt;---- EI &lt;---- Message Builder &lt;---- Incoming Message &lt;---- Service Provider
        </p>
        <p>
            Client &lt;---- Outgoing Message ----&gt; Message Formatter &lt;---- EI &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 EI. Instead they will pass
            through the EI 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>
            EI 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> 
            EI 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 EI 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 EI 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 EI 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 EI.
        All the admin services are running with content type: application/soap+xml. So if 
        a user wants to use admin console and use the EI 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 EI 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>
