+49 228 5552576-0


info@predic8.com

requires version 3.0.0 or higher

SOAP Router Quickstart Tutorial

This tutorial will show you how to setup a service proxy for Web Services that provides URL rewriting in WSDL and message validation against XML Schema definitions. And we will expose the Web Service as a REST resource.

In the tutorial you will get to know the basic functionality and principles of Membrane. After the tutorial you can have a look at the examples showing you additional features of Membrane.

To run the example do the following:

  1. Download Membrane Router version 3.0.0 or above.
  2. Execute router.bat in the MEMBRANE_HOME/examples/quickstart-soap directory.
  3. The script router.bat will start the router and load the quickstart-soap.proxies.xml file.

    				<proxies>
    					<serviceProxy name="BLZ" port="2000">
    					<target host="www.thomas-bayer.com" port="80" />
    					</serviceProxy>
    				</proxies>				
    				
    Listing 1: proxies.xml

    Thats all to setup a reverse proxy. Pretty easy isn't it? The serviceProxy will listen at port 2000 at the localhost for HTTP messages. If it receives a message it will be forwarding to thomas-bayer.com at port 80.

    To test it open

    http://localhost:2000

    in your browser. You will see a Web Page. But we are not interested in Web Pages in this tutorial. So continue with step 3.

  4. Now take a look at the WSDL at the following URL.
  5. http://localhost:2000/axis2/services/BLZService?wsdl

    You will see the WSDL description of the sample Web Service.

Rewriting URLs in WSDL and Referenced Schema Documents

  1. Add a WSDLRewriter to the serviceProxy named BLZ.
  2.         <proxies>
              <serviceProxy name="BLZ" port="2000">
                <wsdlRewriter />
                <target host="www.thomas-bayer.com" port="80" />
              </serviceProxy>
            </proxies>
          
    Listing 2: WSDL Rewriter

  3. Take a look at the WSDL again:
  4. http://localhost:2000/axis2/services/BLZService?wsdl

  5. At the end of the WSDL you will notice the rewritten endpoint addresses of the service.
  6.         <wsdl:service name="BLZService">
              <wsdl:port name="BLZServiceSOAP11port_http"  
                   binding="tns:BLZServiceSOAP11Binding">
                <soap:address  
            location="http://localhost:2000/axis2/services/BLZService">
                </soap:address>
              </wsdl:port>
              <wsdl:port name="BLZServiceSOAP12port_http" 
                   binding="tns:BLZServiceSOAP12Binding">
                <soap12:address location="http://localhost:2000/axis2/services/BLZService">
                </soap12:address>
              </wsdl:port>
              <wsdl:port name="BLZServiceHttpport" 
                   binding="tns:BLZServiceHttpBinding">
                <http:address location="http://localhost:2000/axis2/services/BLZService">
                </http:address>
              </wsdl:port>
            </wsdl:service>
          
    Listing 3: Rewritten endpoint addresses

    The original hostname www.thomas-bayer.com was replaced by the domain name used to access the WSDL.

  7. Replace the localhost with the hostname of your computer.
  8. E.g: http://<your-hostname>:2000/axis2/services/BLZService

  9. Take a look at the endpoint address of the WSDL again.

Administration Console

Membrane Router provides a Web console that allows you to view and list proxy definitions.

  1. Open the quickstart-soap.proxies.xml file in an editor.
  2. Add an additional serviceProxy containing an adminConsole element.
  3.         <proxies>
              <serviceProxy name="BLZ" port="2000">
                <target host="www.thomas-bayer.com" port="80" />
                <wsdlRewriter/>
              </serviceProxy>
              <serviceProxy name="Console" port="9000">
                <adminConsole />
              </serviceProxy>
            </proxies>					
          
    Listing 4: Service Proxy for Admin Console

  4. Open the following URL in your browser:
  5. http://localhost:9000/admin

  6. Now you will see a list containing the service proxies you have defined in the proxies.xml file.
  7. AdminConsole

    Figure1: AdminConsole

Exposing SOAP Services as REST Resources

With the Rest2Soap interceptor you can make a SOAP Web Service as a REST resource accessible.

  1. Add a Rest2Soap interceptor to the serviceProxy.
  2.         <proxies>
              <serviceProxy name="BLZ" port="2000">
                <rest2Soap>
                  <mapping regex="/bank/.*" soapAction=""
                    soapURI="/axis2/services/BLZService" 
                    requestXSLT="get2soap.xsl"
                    responseXSLT="strip-env.xsl" />
                </rest2Soap>
                <wsdlRewriter />
                <target host="www.thomas-bayer.com" port="80" />
              </serviceProxy>
            
              <serviceProxy name="Console" port="9000">
                <adminConsole />
              </serviceProxy>	
            </proxies>
          
    Listing 5: Rest2Soap Interceptor

  3. Open the following URL:
  4. http://localhost:2000/bank/37050198

    You will receive a response like the following:

            <ns1:getBankResponse 
              xmlns:ns1=http://thomas-bayer.com/blz/  
              xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
                <ns1:details>
                  <ns1:bezeichnung>Sparkasse KölnBonn</ns1:bezeichnung>
                  <ns1:bic>COLSDE33XXX</ns1:bic>
                  <ns1:ort>Köln</ns1:ort>
                  <ns1:plz>50667</ns1:plz>
                </ns1:details>
            </ns1:getBankResponse>
          
    Listing 6: Response of BLZService

Although the service is now exposed as a REST resource you can still call it with a SOAP client. Notice the regex attribute of the mapping element within the Rest2Soap interceptor. Only URLs matching that regex will be transformed to SOAP messages.

Validating SOAP Messages against WSDL and Referenced Schemas

A serviceProxy can validate SOAP messages against WSDL definitions and XML Schemas.

  1. Add a validator to the serviceProxy and specify the URL of the WSDL.
  2.         <proxies>
              <serviceProxy name="BLZ" port="2000">
                <rest2Soap>
                  <mapping regex="/bank/.*" soapAction=""
                    soapURI="/axis2/services/BLZService" 
                    requestXSLT="get2soap.xsl"
                    responseXSLT="strip-env.xsl" />
                </rest2Soap>
                <validator
                  wsdl="http://www.thomas-bayer.com/axis2/services/BLZService?wsdl" />
                <wsdlRewriter />
                <target host="www.thomas-bayer.com" port="80" />
              </serviceProxy>
            
              <serviceProxy name="Console" port="9000">
                <adminConsole />
              </serviceProxy>	
            </proxies>
          
    Listing 7: Soap Validator

You must not specify the locations of schemas referenced from the WSDL cause the validator will extract their locations from the WSDL document.

We call the Web Service to test the validator. In the following steps we will use soapUI, but you can also use every other SOAP client as well.

  1. Start soapUI
  2. Create a soapUI Projekt with the following parameters:
  3. New soapUI Project for BLZ Service

    Figure2: New soapUI Project for BLZ Service

    On the left side expand everything within the BLZServiceSOAP11Binding entry.

    Bindings and Operations of the BLZ Service

    Figure3: Bindings and Operations of the BLZ Service

  4. DblClick on the Request 1 entry.
  5. On the right side a request template will be created for you.

    Request Template for the getBank Operation

    Figure4: Request Template for the getBank Operation

  6. Complete the request as follows and push the play button at the top left corner.
  7.         <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:blz="http://thomas-bayer.com/blz/">
               <soapenv:Header/>
               <soapenv:Body>
                  <blz:getBank>
               <blz:blz>37050198</blz:blz>
                  </blz:getBank>
               </soapenv:Body>
            </soapenv:Envelope>
          
    Listing 8: Example Request for getBank Operation

    You will receive the following response:

            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
               <soapenv:Body>
                  <ns1:getBankResponse xmlns:ns1="http://thomas-bayer.com/blz/">
               <ns1:details>
                  <ns1:bezeichnung>Sparkasse KölnBonn</ns1:bezeichnung>
                  <ns1:bic>COLSDE33XXX</ns1:bic>
                  <ns1:ort>Köln</ns1:ort>
                  <ns1:plz>50667</ns1:plz>
               </ns1:details>
                  </ns1:getBankResponse>
               </soapenv:Body>
            </soapenv:Envelope>
          
    Listing 9: Response for Example Request

  8. Make the request invalid by adding a foo element and push the play button again.
  9. 					<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    							  xmlns:blz="http://thomas-bayer.com/blz/">
    					   <soapenv:Header/>
    					   <soapenv:Body>
    					      <blz:getBank>
    						 <blz:blz>foo</blz:blz>
    						    <foo/>
    					      </blz:getBank>
    					   </soapenv:Body>
    					</soapenv:Envelope>
    				
    Listing 10: Invalid getBank Request

    You will get a error message like the following:

    					<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    					   <soapenv:Body>
    					      <soapenv:Fault>
    						 <faultcode>soapenv:Server</faultcode>
    						 <faultstring>Message validation failed!</faultstring>
    						 <detail>Validation failed: org.xml.sax.SAXParseException: cvc-complex-type.2.4.d: Invalid content was found starting with element 'foo'. No child element is expected at this point.;</detail>
    					      </soapenv:Fault>
    					   </soapenv:Body>
    					</soapenv:Envelope>
    				
    Listing 11: Validation Fault Response

Copyright © 2008-2014 predic8 GmbH
Moltkestr. 40, 53173 Bonn, Tel. +49 (228) 555 25 76-0