XPE Tutorials - Tutorial 1 - Basic XPE Pipeline

• 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 1 - Basic XPE Pipeline

Description

The first and most basic concept that you need to be aware of is that all XPE requests are invoked by issuing any of the five HTTP verbs (GET, PUT, POST, DELETE, HEAD) to a URL registered to XPE. If you now perform a GET on the URL http://localhost:8188/xpe/tutorial/tut1/echo, you should get an error similar to:
HTTP ERROR: 404

No pipe found

RequestURI=/xpe/tutorial/tut1/echo

Powered by XPE://



This is because although the XPE server is running, there is no service registered at the specified URL.

Step 1 - Register (Define) an XPE Service

Registering a service is accomplished by adding a line similar to:

in the file xar/META-INF/xpipedef.xml. In essence this file contains all the registered XPE pipes for the application.

The xar/META-INF/xpipedef.xml file should look like:

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. This is accomplised by adding the mapping to the file xar/META-INF/urlPattern.xml:

These two entries need to be considered as a unit in order to understand how an outside HTTP request gets processed by XPE. The pattern defined in the urlPattern.xml file, namely /tutorial/tut1/echo defines a URI available to the outside world as http://localhost:8188/xpe/tutorial/tut1/echo . The xpipe mapping: http://www.xml.org/pipe/xpe/tutorial/tut1/echo parameter then defines the internal XPE pipe. Here for simplicity it just maps to tutorial/tut1/echo. That is the part after http://www.xml.org/pipe/xpe

Step 3 - Defining the XML Pipe processing

The last thing required before completing our first xml pipe is to actually define what the pipe needs to do. Remember up till now what we have done is just define the service end-point of our pipe and the url that maps to that end point. To add behaviour to our pipe we need to add a

We will add a source node that will accept a http request and convert it into a set of XML SAX events This is done by adding an xnode element and specifying a 'http' type source:

Next we need to add a sink node that will serialise the XML SAX stream into a http response.

In effect we will return an XML representation of a http request. Note the sink property named "method" and set to "xml". This is what actually defines the serialisation to be XML for the http sink.

You may at any time refer to the online XPE manual to get further details about any of the XPE xnode and xsink components. For example to view the full documentation for the http source component go to the URL http://localhost:8188/xpe/manual/source/httpRequest

That's it. You should now have three files that look like the following:

xar/META-INF/urlPattern.xml

xpipedef.xml

xar.xml

Step 4 - build and deploy

The final step we need to do is build the application. simple use your favourite IDE to run the ant build.xml file. This will produce a file called tutorial.xar in the application build directory.

To deploy the application use a browser to go to the /xpe/xar url:

• http://localhost:8188/xpe/xar

You should see a page similar to:

Browse to the build directory under your project directory and select the file called tutorial.xar. This is the deployable xpe archive file that contains your xpe application.

The browser should now look something like:

Now deploy the application. XPE should respond with a page full of XML. Look through this page for any exceptions or errors. If there are none, then the application has been successfully deployed.

Step 5 - Testing our pipeline

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/tut1/echo

You should now see a page similar to:

If you do see this page, congratulations, you have created and deployed your first XPE pipeline application.

Before continuing, lets look at this output and understand what is going on. When you deployed the tutorial application, the XPE server installed the application and started listening for any requests that matched the url that we defined earlier.

It then routed requests matching this url to the XPE service we defined. This Service then transformed the HTTP request into a stream of XML SAX events via a http source xnode. This series of events were then passed to the http sink xsink which converted SAX events back to XML text that was then added to the HTTP response.

Analysing the XML output

Now that we can see some output from the XPE pipeline, lets take a closer look. The XML displayed in your browser should look something like:

There are numerous points of interest in this XML which we will make more and more use of as the tutorials progress and as your XPE skills increase.

For now lets take a look at some of the more interesting pieces of information found in this XML response:

First notice that the outermost (root) element is the httpRequest element and notice that its namespace is http://www.xml.org/pipe/HTTP. Within this element there are a number of attributes that we can make use of:

• requestURL (http://localhost:8188/xpe/tutorial/tut1/echo) - Tells us the URL used to access the service
• sessionID (48f47fbee12a08c1) - Tells us that a session has been created for the request. By default XPE will create a new session if one does not already exist for the request.
• method (GET) - The HTTP method specified with the request
• All the HTTP Headers have also been converted to XML format, including any cookies.

Before leaving this tutorial try the following url: http://localhost:8188/xpe/tutorial/tut1/echo?user=fred&password=flintstone. Look at the XML echoed back. Notice that each parameter passed in the URL is represented within the h:params element:

Summary

This tutorial has illustrated how to create the simplest of XPE pipelines. It has introduced a number of XPE fundamentals that must be understood to create more complex XPE pipelines. The next tutorial will demonstrate how we can access parameters from a HTTP GET request and use these parameters from within an XML pipeline.

Any Problems?

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