Envelope Wrapper

This section explains, through an example scenario, how the Envelope Wrapper EIP can be implemented using WSO2 ESB. The following topics are covered:

Introduction to Envelope Wrapper

The Envelope Wrapper EIP allows existing systems to participate in a messaging exchange that places specific requirements on the message format, such as message header fields or encryption. It wraps application data inside an envelope that is compliant with the messaging infrastructure. The message is unwrapped when it arrives at the destination. For more information, refer to http://www.eaipatterns.com/EnvelopeWrapper.html.

Figure 1: Envelope Wrapper EIP

Example scenario

This example scenario receives a message with application data wrapped inside an envelope, unwraps the message, and sends it to a specific endpoint. The sender sends the request inside a SOAP envelope. Once the ESB receives the envelope, it unwraps it and sends it as a Plain Old XML (POX) request to the sample back-end Axis2 server.

The diagram below depicts how to simulate the example scenario using the WSO2 ESB.

Figure 2: Example Scenario of the Envelope Wrapper EIP

Before digging into implementation details, let's take a look at the relationship between the example scenario and the Envelope Wrapper EIP by comparing their core components.

Envelope Wrapper EIP (Figure 1)	Envelope Wrapper Example Scenario (Figure 2)
Wrapper	Stock Quote Request wrapped in SOAP
Messaging System	WSO2 ESB
Unwrapper	Address Endpoint format
Recipient	Stock Quote Service Instance

An alternative implementation of this EIP is to have the Address Endpoint wrap from one envelope format to another (for example, wrapping a SOAP 1.1 envelope in a SOAP 1.2 envelope).

Environment setup

Download and install WSO2 ESB from http://wso2.com/products/enterprise-service-bus. For a list of prerequisites and step-by-step installation instructions, refer to Getting Started in the WSO2 ESB documentation.
Start the sample Axis2 server. For instructions, refer to the section ESB Samples Setup - Starting Sample Back-End Services in the WSO2 ESB documentation.

ESB configuration

Start the ESB server and log into its management console UI (https://localhost:9443/carbon). In the management console, navigate to Main Menu, click Service Bus and then Source View. Next, copy and paste the following configuration, which helps you explore the example scenario, to the source view.

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://ws.apache.org/ns/synapse">
   <proxy name="EnvelopeUnwrapProxy"
          transports="https http"
          startOnLoad="true">
      <target>
         <endpoint>
            <address uri="http://localhost:9000/services/SimpleStockQuoteService"
                     format="pox"/>
         </endpoint>
         <outSequence>
            <send/>
         </outSequence>
      </target>
      <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
   </proxy>
   <sequence name="fault">
      <log level="full">
         <property name="MESSAGE" value="Executing default &#34;fault&#34; sequence"/>
         <property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
         <property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
      </log>
      <drop/>
   </sequence>
   <sequence name="main">
      <send/>
   </sequence>
</definitions>

Simulating the sample scenario

Send the following request using a SOAP client like SoapUI, and monitor the message using TCPMon.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.samples" xmlns:xsd="http://services.samples/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getQuote>     
         <ser:request>           
            <xsd:symbol>foo</xsd:symbol>
         </ser:request>        
      </ser:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

Notice that the request data is inside a SOAP envelope. When the request was monitored through TCPMon before it was sent to the ESB, it was structured as follows:

POST /services/EnvelopeUnwrapProxy HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
SOAPAction: "urn:getQuote" 
Content-Length: 385 
Host: 127.0.0.1:8281 
Connection: Keep-Alive 
User-Agent: Apache-HttpClient/4.1.1 (java 1.5) 
 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.samples" xmlns:xsd="http://services.samples/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getQuote>     
         <ser:request>           
            <xsd:symbol>foo</xsd:symbol>
         </ser:request>        
      </ser:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

The request sent to the back-end Axis2 server has the following structure:

POST /services/SimpleStockQuoteService HTTP/1.1 
Content-Type: application/xml; charset=UTF-8 
Accept-Encoding: gzip,deflate 
SOAPAction: urn:getQuote 
Transfer-Encoding: chunked 
Host: localhost:9000 
Connection: Keep-Alive 
User-Agent: Synapse-HttpComponents-NIO 
 
e0 
<ser:getQuote xmlns:ser="http://services.samples">     
         <ser:request>           
            <xsd:symbol xmlns:xsd="http://services.samples/xsd">foo</xsd:symbol>
         </ser:request>        
      </ser:getQuote> 
0

This means that the SOAP envelope was removed by the ESB.

How the implementation works

Let's investigate the elements of the ESB configuration in detail. The line numbers below are mapped with the ESB configuration shown above.

address [line 8 in ESB config] - The endpoint address contains the attribute format='pox', which makes the ESB convert incoming requests to Plain Old XML. Other supported formats for wrapping include soap11, soap12 and get. For more information, refer to the Address Endpoint mediator.