XPE Tutorials - Tutorial 2 - Passing parameters to Pipelines

• Getting started
  • Tutorial 1 - Basic XPE Pipeline
  • Tutorial 2 - Passing Parameters to Pipelines
  • Tutorial 3 - Accessing an SQL database
  • Tutorial 4 - POSTing XML to an XPE Pipeline
  • Tutorial 5 - Creating a simple form

Tutorial 2 - Passing parameters to Pipelines

Description

This tutorial will show you how to extract and manipulate request parameters from a HTTP request.

We will be creating the following XPE pipeline:

Our first pipeline just echoed back a HTTP GET request submitted from a browser as an XML document in a HTTP Response. This tutorial will now extract a username and password passed as request parameters and compare them against some hardcoded values returning an indication of whether the username/password is valid or invalid. (A later tutorial (SQL) will compare the passed parameters agains those in a database)

Before proceeding enter the HTTP request from the previous tutorial to make sure XPE is listening and working correctly by navigating to the following URL:

http://localhost:8188/xpe/tutorial/tut1/echo?username=fred&password=flintstone

You should see something similar to:

Notice how the username and password parameters are represented in the XML stream under the params elements. Lets see how we can access these parameters from an XPE pipeline.

Step 1 - Register (Define) a new XPE Service

Recall that registering a service is accomplished by adding a line similar to:

in the file xar/META-INF/xpipedef.xml. We will now register a new service called authenticate. Edit the xpipedef.xml file so that it looks like:

This will define our new service. At present it will just echo our request like our initial service. But we will change that soon

Step 2 - Mapping a URl to a Service

Next we need to define a url mapping that will allow outside users to access this service. Recall that this is accomplised by adding the mapping to the file xar/META-INF/urlPattern.xml:

Now if you build and deploy the application you should be able to use the url:

http://localhost:8188/xpe/tutorial/tut2/authenticate?username=fred&password=flintstone

At this stage it still just acts as an echo pipeline like tutorial 1. But not for long...

Step 3 - Defining the XML Pipe processing

This is where we will begin changing the pipe definition to begin doing some business processing. What we wish to do is:

1. extract the username and password parameters;
2. compare them against some predefined values;
3. return an indication of whether the two sets match.

We will do this by adding an XSLT transformation to the pipe. Edit the pipe definition in the xpipedef.xml so that it looks like:

What we have done here is:

1. Defined (Registered) a new node type uri - xslt/authenticate that references a file: ROOT/xslt/authenticate.xsl. This file is an XSL Transformation that will act on the XML SAX event stream emminating from the http source xnode.
2. Changed the tut2/authenticate pipe to add a xnode filter referencing this transformation element after the source xnode and before the http sink.

Step 4 - Defining the transformation

We now need to write the XSL transformation that extracts the username/password parameters, compares them against our hardcoded ones, and produces our final result.

If you are familiar with XSLT and pipelines, you may wish to try your hand at this transformation. If so just create the file in the directory ROOT/tutorial/xslt and call it authenticate.xsl. In this way it will match the uri that we specified in the xpipedef.xml file.

If you are new to either XSL and/or XML pipes, you can copy the file from the worked solutions directory.

Lets take a quick look at the contents of the xslt transformation and see what is happening.

Lets quickly analyse this stylesheet

First of all note that the stylesheet version is set to 2.0 to indicate that xsl 2.0 elements/functions are being used by the stylesheet. When using XPE you should always use version 2.0 as it is significantly more powerfull than version 1.0

The next point of interest is the match element that matches the http:httpRequest element of our XML stream. Within this match we look to see if a username and password parameter has been specified. If not an error condition is output. If a username and password has been provided, then a check is made to see if the username matches fred and the password matches flintstone. If they do then a successfull result is output otherwise an error condition is output.

Step 5 - Testing our pipeline

Now build and deploy the application. XPE should respond with a successfull deployment page. If no errors are reported, then the application has been successfully deployed.

You can test that the application has been deployed by trying to navigate to the url that identifies your new XPE service:

• http://localhost:8188/xpe/tutorial/tut2/authenticate?username=fred&password=flintstone

The XPE result should be similar to:

Now try issueing a GET using a wrong password or without specifying a password at all.

You should see the two different error conditions output:

Summary

This tutorial has illustrated how simple it is to extract request parameters from a HTTP GET request. The next tutorial will show how XPE interfaces to SQL database, extracting data and automaticaly generating XML from the SQL resultset that can be used within an XPE pipeline.

Any Problems?

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