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:

Download Membrane Router version 3.0.0 or above.

Execute router.bat in the MEMBRANE_HOME/examples/quickstart-soap directory.

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.

Now take a look at the WSDL at the following URL.

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

Add a WSDLRewriter to the serviceProxy named BLZ.

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

Listing 2: WSDL Rewriter

Take a look at the WSDL again:

http://localhost:2000/axis2/services/BLZService?wsdl

At the end of the WSDL you will notice the rewritten endpoint addresses of the service.

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

Replace the localhost with the hostname of your computer.

E.g: http://<your-hostname>:2000/axis2/services/BLZService

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.

Open the quickstart-soap.proxies.xml file in an editor.

Add an additional serviceProxy containing an adminConsole element.

        <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

Open the following URL in your browser:

http://localhost:9000/admin

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

Figure 1: AdminConsole

Exposing SOAP Services as REST Resources

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

Add a Rest2Soap interceptor to the serviceProxy.

        <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

Open the following URL:

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.

Add a validator to the serviceProxy and specify the URL of the WSDL.

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

Start soapUI

Create a soapUI Projekt with the following parameters:

Figure 2: New soapUI Project for BLZ Service

On the left side expand everything within the BLZServiceSOAP11Binding entry.

Figure 3: Bindings and Operations of the BLZ Service

DblClick on the Request 1 entry.

On the right side a request template will be created for you.

Figure 4: Request Template for the getBank Operation

Complete the request as follows and push the play button at the top left corner.

        <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

Make the request invalid by adding a foo element and push the play button again.

					<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