Tutorial 4 POSTing XML to an XPE Pipeline

Description

This tutorial will demonstrate how data can be POSTed to an XPE pipeline.

We will alter the pipeline from Tutorial 3 to simply accept an XML posted to it as well as a HTTP request having parameters. This increases the flexibility of our pipelines and illustrates how XPE can support RESTfull web services (without the need of SOAP).

Step 1 - Define the XML to send

Since our Tutorial 3 pipeline is about authenticating a username/password pair against a database, then all that is required is a simple XML such as:

<authenticate  xmlns="http://www.xmlpipe.org/xpe/manual" >
   <username>
      fred
   </username>
   <password>
      flintstone
   </password>
</authenticate>

Posting the XML

Apart from the XML itself, we need a way of posting the XML to our Pipeline. In this case a browser is of no use as they are built to perform HTTP GET requests.

Fortunately there are numerous tools and utilities that can perform this task for us available free on the internet.

A powerfull and simple tool that will perform the job is jmeter . The rest of this tutorial will assume you are using jmeter to post data to our pipelines. If you decide to use another utility, you may need to alter the tutorial somewhat.

Step 2 - Configuring XPE to accept POSTed data

Up untill now we have only configured XPE pipes to accept HTTP GET requests. Recall this is done in the urlPattern.xml file with an entry such as:

<method  name="GET"  xmlns="http://www.xmlpipe.org/xpe/manual" >
   <map  pattern="/tutorial/tut3/dbauthenticate"  xpipe="http://www.xml.org/pipe/xpe/tutorial/tut3/dbauthenticate" />
</method>

To accept HTTP POST requests we simply add the required url pattern as follows:

<method  name="POST"  xmlns="http://www.xmlpipe.org/xpe/manual" >
   <map  pattern="/tutorial/tut3/dbauthenticate"  xpipe="http://www.xml.org/pipe/xpe/tutorial/tut3/dbauthenticate" />
</method>

Add this xml fragment to the urlPattern.xml file. The file should now look like:

<urlPattern  xmlns="http://www.xml.org/xml/pipe" >
   <method  name="GET" >
      <map  pattern="/tutorial/tut1/echo"  xpipe="http://www.xml.org/pipe/xpe/tutorial/tut1/echo" />
      <map  pattern="/tutorial/tut2/authenticate"  xpipe="http://www.xml.org/pipe/xpe/tutorial/tut2/authenticate" />
      <map  pattern="/tutorial/tut3/dbauthenticate"  xpipe="http://www.xml.org/pipe/xpe/tutorial/tut3/dbauthenticate" />
   </method>
   <method  name="POST" >
      <map  pattern="/tutorial/tut3/dbauthenticate"  xpipe="http://www.xml.org/pipe/xpe/tutorial/tut3/dbauthenticate" />
   </method>
</urlPattern>

XPE allows the same pipeline to be shared transparently by both GET and POST requests. Normally all that is required to perform this is to extract the request data differently at the start of the pipeline. This will be illustrated next.

Step 3 - Changing the pipeline to accept HTTP XML body

In tutorial 3 we extracted the username and password from the url parameters. Now we will change the first pipeline filter to optionally extract the username and password from the XML we are posting to the pipeline. To do this change the dbSelect.xsl to something similar to:

<xsl:stylesheet  version="2.0"  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" >
   <xsl:output  method="xml" />
   <xsl:template  match="http:httpRequest" >
      <xsl:choose>
         <xsl:when  test="//http:params/http:param[@name='password'] and //http:params/http:param[@name='username']" >
            <xsl:variable  name="username" >
               <xsl:value-of  select="//http:params/http:param[@name='username']/@value" />
            </xsl:variable>
            <xsl:variable  name="password" >
               <xsl:value-of  select="//http:params/http:param[@name='password']/@value" />
            </xsl:variable>
            <sql:connect  dataSource="tutorial"  xmlns:sql="http://www.softtouchit.com/xpe/sql" >
               <sql:transaction>
                  <sql:query  rowName="authentication" >
                     <sql:sql>
                        SELECT count(username) as recordCount from authentication where username='&lt;xsl:value-of select="$username"/&gt;' and password='&lt;xsl:value-of select="$password"/&gt;'
                     </sql:sql>
                  </sql:query>
               </sql:transaction>
            </sql:connect>
         </xsl:when>
         <xsl:when  test="//authentication" >
            <xsl:variable  name="username" >
               <xsl:value-of  select="//authentication/username" />
            </xsl:variable>
            <xsl:variable  name="password" >
               <xsl:value-of  select="//authentication/password" />
            </xsl:variable>
            <sql:connect  dataSource="tutorial"  xmlns:sql="http://www.softtouchit.com/xpe/sql" >
               <sql:transaction>
                  <sql:query  rowName="authentication" >
                     <sql:sql>
                        SELECT count(username) as recordCount from authentication where username='&lt;xsl:value-of select="$username"/&gt;' and password='&lt;xsl:value-of select="$password"/&gt;'
                     </sql:sql>
                  </sql:query>
               </sql:transaction>
            </sql:connect>
         </xsl:when>
         <xsl:otherwise>
            <result  status="error"  xmlns="" >
               <error>
                  username and password are required parameters.
               </error>
            </result>
         </xsl:otherwise>
      </xsl:choose>
   </xsl:template>
</xsl:stylesheet>

Note

Again, please ensure that the stylesheet above declares the namespaces:

in the xsl:stylesheet element. The above is slightly incorrect due to a prementioned documentation formatting bug.

In this xslt file we have added code to detect the presence of an authentication element. If found then the username and password will be extracted from the username and password child elements. The sql for the authentication will then be created from these values. The remainder of the pipeline will function as before.

Build and deploy the application and check for any deployment errors.

Post this XML to our tutorial pipeline using your utility of choice. a sample jmeter test is included in the tutorials/solutions/tutorial4 directory. If you use jmeter, then the client would look something like:

Now once you POST this data to our pipeline, you should either receive a success result:

<result  status="success" />

if the username/password match those in the database, or an error result if they do not:

<result  status="error" >
   <error>
      Username not found or password is invalid.
   </error>
</result>

Summary

This tutorial has demonstrated:

The next tutorial will illustrate how XPE can be used to generate and process FORMS utilising simple RESTfull web services for business processing.

Any Problems?

If you have problems getting this tutorial to work look at the completed solution in the tutorials/solutions/tutorial4 directory It should have all files required to buld and run the tutorial.