Selective Consumer

Introduction to Selective Consumer

The purpose of this EIP is to demonstrate how the WSO2 ESB can be used to implement the Selective Consumer EIP - it ensures that a specific receiver only processes messages that have been pre-filtered based on certain criteria.

Example Scenario for the EIP

In the given scenario, the Axis2 server acts as the consumer. The consumer criteria is specified through an XML schema validation which is stored as a local entry in the registry. Messages which are sent to the ESB are validated to match the criteria of the schema using the validate mediator. The message will be allowed to be consumed only if the message meets the validation criteria.

Implementing the Example Scenario in WSO2 ESB

Getting Started

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

Before digging into implementation details, let's take a look at the co-relation of the example scenario and the Selective Consumer EIP by comparing their core components.

Figure 1: Selective Consumer EIP	Figure 2: Selective Consumer Example Scenario
Specifying Producer	Simple Stock Quote Client
Messages with Selection Values	Simple Stock Quote Request
Selective Consumer	Schema Validator
Receiver	Simple Stock Quote Server

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 toInstallation Guide 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.

ESB Configuration

3. Start the WSO2 ESB and copy the following configuration to the "Source View" in the management console (Main Menu -> Service Bus -> Source View), using which the example scenario can be explored.

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://ws.apache.org/ns/synapse">
   <localEntry key="selective_criteria">
      <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
                 xmlns="http://www.apache-synapse.org/test"
                 elementFormDefault="qualified"
                 attributeFormDefault="unqualified"
                 targetNamespace="http://services.samples">
         <xs:element name="getQuote">
            <xs:complexType>
               <xs:sequence>
                  <xs:element name="request">
                     <xs:complexType>
                        <xs:sequence>
                           <xs:element name="stockvalue" type="xs:string"/>
                        </xs:sequence>
                     </xs:complexType>
                  </xs:element>
               </xs:sequence>
            </xs:complexType>
         </xs:element>
      </xs:schema>
   </localEntry>
   <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">
      <in>
         <validate>
            <schema key="selective_criteria"/>
            <on-fail>
               <makefault>
                  <code xmlns:tns="http://www.w3.org/2003/05/soap-envelope" value="tns:Receiver"/>
                  <reason value="Invalid custom quote request"/>
               </makefault>
               <property name="RESPONSE" value="true"/>
               <header name="To" expression="get-property('ReplyTo')"/>
               <drop/>
            </on-fail>
         </validate>
         <send>
            <endpoint>
               <address uri="http://localhost:9000/services/SimpleStockQuoteService?wsdl"/>
            </endpoint>
         </send>
      </in>
      <out>
         <send/>
      </out>
   </sequence>
</definitions>

Simulating the Sample Scenario

4. Send the following request using a client like SOAP UI.

<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>
         <!--Optional:-->
         <ser:request>
            <!--Optional:-->
            <ser:symbol>IBM</ser:symbol>
         </ser:request>
      </ser:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

Notice that the stock quote request was not processed. Send the following message to the ESB server.

<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>
         <!--Optional:-->
         <ser:request>
            <!--Optional:-->
            <ser:stockvalue></ser:stockvalue>
         </ser:request>
      </ser:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

The consumer has specified the criteria in using a schema validation, only the structure that meets that criteria will be allowed to be consumed.

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 3 above.

localEntry [line 3 in ESB config] - a local registry entry with key 'selective_criteria' is used to define the XML Schema that will be used for validation inside the main sequence.
validate [line 34] in ESB config] - this mediator is used to define the portion of a message that is going to be used for validation - in the case no source attribute is specified using an XPath expression, which makes the ESB perform the validation on the first child of the SOAP body.
scehma [line 35 in ESB config] - this defines which schema to use for validation - in this case the local registry entry definition made in line 3 is used.
on-fail [line 36 in ESB config] - this defines what is to be carried out on failure of a validation - in this case a fault is created and the message is dropped.