Messaging Gateway

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

Introduction to Messaging Gateway

The Messaging Gateway EIP encapsulates message-specific code from the rest of the application. It is a class than wraps messaging-specific method calls and exposes domain-specific methods to the application. Only the Messaging Gateway knows about the actual implementation of the messaging system. Rest of the application calls the methods of the Messaging Gateway, which are exposed to the outside world. For more information, refer to http://www.eaipatterns.com/MessagingGateway.html.

Figure 1: Messaging Gateway EIP

Example scenario

This example scenario demonstrates creating a proxy service with a publishWSDL element. The published WSDL's methods act as the Message Gateway, hiding details of the actual back-end service, and exposing only domain-specific methods to the client application. 

Proxy services in WSO2 ESB act as Messaging Gateways, abstracting away details of actual back end services from implementing clients. For a more complex example of how the WSO2 ESB can act as a Messaging Gateway, refer to Health Care Scenario where a single Proxy Service acts as a Messaging Gateway between several back-end services.

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

Figure 2: Example Scenario of the Messaging Gateway EIP

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

Environment setup

1. Download an install the 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.
2. Start the sample Axis2 server. For instructions, refer to section ESB Samples Setup - Starting Sample Back-End Services in the WSO2 ESB documentation. 
3. Copy sample_proxy_3.wsdl file in to <ESB_HOME>/repository/samples/resources/proxy directory. 

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.

<definitions xmlns="http://ws.apache.org/ns/synapse">
   <proxy name="StockQuoteProxy" startOnLoad="true">
      <target>
         <endpoint>
            <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
         </endpoint>
         <outSequence>
            <send/>
         </outSequence>
      </target>
      <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_3.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">
      <log/>
      <drop/>
   </sequence>
</definitions>

Simulating the sample scenario

 If you navigate to http://localhost:9000/services/SimpleStockQuoteService, you can see the WSDL file of the back-end server. There are five methods exposed to the outside, but the Proxy Service SimpleQuoteProxy exposes only four to the outside. It filters out the getFullQuote method. See the SimpleQuoteProxy WSDL file in http://localhost:8280/services/StockQuoteProxy?wsdl.

Send the following request using a client like SOAP UI to the SimpleQuoteProxy service.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://services.samples" 
xmlns:xsd="http://services.samples/xsd">
   <soap:Header/>
   <soap:Body>
      <ser:getFullQuote>
         <!--Optional:-->
         <ser:request>
            <!--Optional:-->
            <xsd:symbol>WSO2</xsd:symbol>
         </ser:request>
      </ser:getFullQuote>
   </soap:Body>
</soap:Envelope>

After sending the above message to the server, you'll get a server error as 'The endpoint reference (EPR) for the Operation not found is /services/StockQuoteProxy and the WSA Action = urn:getFullQuote.' The reason is because getFullQuote method is not exposed to SimpleQuoteProxy although the back-end server supports it.

Now, change the publish WSDL file as follows and send the same SOAP message to the server again.

...
<publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
...

Note that you get the correct response from the server since the new WSDL of the proxy service is the same as the back-end service. 

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 illustrated in step 4 above. 

• proxy [line 2 in ESB config] - Defines a new Proxy Service called StockQuoteProxy. 
• endpoint [line 4 in ESB config] - The endpoint mediator defines the endpoint this proxy service is connected to. That is, the actual back-end service address. 
• publishWSDL [line 11 in ESB config] - The publishWSDL mediator defines the WSDL file to expose for this proxy service. If no publishWSDL is given, the actual back-end service's WSDL is exposed.