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

What is an XPE - XML pipeline?

Before defining the pipeline for this tutorial, we should consider how an XPE pipeline is defined and briefly explain the structure of an XPE/XML pipeline.

Structure of an XPE/XML Pipeline

An XPE/XML Pipeline is in essence a stream of SAX Events having:

• a beginning - where XML SAX events are initially created (source node);
• zero or more intermediate xml processing steps where the initial XML event stream is manipulated(filter nodes);
• an end - where the XML SAX events are serialised into a form understood by the calling client (sink node).

The following illustrates the basic XML Pipe architecture:

An XPE/XML pipe is defined within XPE by:

• defining an outer <register> element having an attribute: uri that is used to uniquely identify the pipeline;
• An inner <xpipe> element that will contain all the pipeline nodes:
  1. source pipeline node
  2. filter pipeline nodes
  3. sink pipeline node

Every pipeline must contain a single source node at the start of the pipeline. Source nodes have the task of generating the initial XML (SAX) stream of events that propagate along the pipeline.

XPE supports different source nodes that allow the XML events to be generated from different sources, for example, the XML events may be generated from:

• a static file that contains the XML;
• a file directory - in which the generated XML will reflect to structure and contents of the directory;
• a http request - probably the most popular source. In this case the generated XML events will reflect the HTTP Request sent to the pipeline.

Every pipeline May contain zero or more filter nodes. Filter nodes transform the stream of XML events in some way. For example filter nodes may:

• Add xml to the stream of existing xml;
• Remove xml from the stream of existing xml;
• Transform (mutate) the existing stream of xml from one form to another;

Finaly, an XML pipeline must contain a single sink node as the last node of a pipeline to serialise the xml stream into a form that can be understood by the calling client.

Example serialisations include:

• html
• xml
• pdf
• zip

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.

Important XPE files

There are four important XPE files that you will need to become familiar with when working with XPE are:

• xar/META-INF/xar.xml
• xar/META-INF/urlPattern.xml;
• xar/META-INF/xpipedef.xml
• xar/META-INF/db.xml

xar.xml

The xar.xml file contains some basic parameters applicable to an application. The following is an example of such a file:

The most important parameter in this file is the baseURI attribute of the <xar:xar> element.

This attribute determines (as the name implies) the base URI for all pipelines within this application. In the case of our tutorials, the uri is: http://www.xml.org/pipe/xpe/tutorial.

This uri is a logical uri that should contain a value that clearly identifies your application and web domain. Don't confuse this logical uri with the physical uri of your XPE pipelines in the deployed environment. For example, if you are developing an application that deals with account resources for an organisation with a web domain of www.somecompany.org, then the base uri could be something like http://www.somecompany.org/account etc. In the deployed environment though, the pipelines might be accessed via the physical uri: http://localhost:8888/account or http://www.test.somecompany.org/account

All uri's defined within an XPE application will have this logical uri as a base. We will see how this works next when we look at the urlPattern and xpipedef.xml files.

urlPattern.xml

The urlPattern.xml file defines all the url patterns that an application supports. XPE is based on HTTP and REST principles, so all access to XPE are handled by using the common HTTP verbs in conjunction with XPE (XML) pipes that are identified by unique URL's.

The structure of a urlPattern.xml file is very simple. The following example illustrates such a file:

This file contains a mandatory root element <urlPattern>. Within this element there can be multiple <method> elements. These <method> elements define the various uri patterns that may be exposed to the HTTP Verb methods identified by the name attribute.

In the above example, we see that the "/tutorial/tut1/echo" pattern is being exposed via the "GET" method, while the "/tutorial/tut3/dbauthenticate" pattern is being exposed via the "POST" method.

Within every <method> element there may be any number of <map> elements. These elements map a http path to an actual XPE pipeline.

The pattern attribute is an expression that allows multiple uri patterns to map to a single XPE pipeline. The value of the pattern attribute is the URI relative to the XPE server instance being used. That is it matches the path part of a URI.

For example a commonly used pattern within an XPE application is that used to map binary resources such as images and .css files etc:

Hopefully all the talk of logical and physical URIs has not confused you too much. If so don't worry, it should get clearer as we progress through the tutorials.

xpipedef.xml file

The xpipedef.xml file contains the XPE pipeline definitions.

This file allows the registration of various XPE resources - such as XSLT stylesheets and the registration and implimentation of the XPE pipelines that an application provides. Instead of explaining the structure and content of this file here (as it is probably the most complex of the XPE files), we will slowly build up our knowledge of this file as we progress through the tutorials.

db.xml

The xar/META-INF/db.xml file is used to define database connection parameters.

The following example illustrates the basic structure of this file:

The above db.xml file defines the connection parameters required to access a mysql database.

Again, we will not delve too deeply into this file at the moment as tutorial 4 will illustrate database access using XPE.

Thats probably all the background information required at this stage regarding these files. Lets start our first tutorial...

Step 1 - Configure our xar.xml file

Our first task is to create the xar/META-INF/xar.xml and define a baseURI for our tutorials:

1. Create the file xar.xml file in the META-INF subdirectory of your tutorial folder/directory. A skeleton project directory (along with completed tutorials) is available from tutorials.zip
2. Create the root element and name it <xar> giving it a namespace of http://www.xml.org/pipe/xpe/xar. Set the baseURI attribute of this element to: http://www.xml.org/pipe/xpe/tutorial
3. Lastly create a description element as a child element of the <xar> element and give a simple description of the tutorial application.

The file should look something like:

Step 2 - Register (Define) an XPE Service

Next we need to register the XPE pipe that will provide our echo 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 an application.

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

What this says is that the URI path tut1/echo is now a registered XPE pipeline. Actually the registered URI is http://www.xml.org/pipe/xpe/tutorial/tut1/echo. This is formed by adding the uri path specified here (tut1/echo) to the baseURI specified in the xar.xml file (http://www.xml.org/pipe/xpe/tutorial).

Step 3 - 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:

The two attributes of the map element (pattern, xpipe) need to be considered as a unit in order to understand how an outside HTTP request gets mapped to and processed by an XPE pipeline

The pattern defined in the urlPattern.xml file, namely /tutorial/tut1/echo defines a URI available to the outside world as http://<ipaddress>:8188/xpe/tutorial/tut1/echo (Assuming XPE is running on the local host on port 8188 - This pipe can be accessed from the local machine on the uri: http://localhost:8188/xpe/tutorial/tut1/echo).

This URI is made up from:

• XPE Host Listen address: http://<ipaddress>:8188
• XPE Context Path from the server.xml file: /xpe
• pattern from urlPattern.xml: /tutorial/tut1/echo

The xpipe mapping: http://www.xml.org/pipe/xpe/tutorial/tut1/echo parameter then defines the internal XPE pipe that will be invoked by the XPE server once a request for the URI is sent to it. This mapping is made up by combining:

• The baseURI specified in the xar.xml file: http://www.xml.org/pipe/xpe/tutorial
• Any string that makes sense and ensures a unique pipeline name: /tut1/echo

Step 4 - Defining the XML Pipe processing

The last thing required before completing our first xml pipe is to actually define the pipe and specify its behaviour.

The pipeline for this first tutorial is very simply - it just echos back our http request in XML format. So all we need to do is register and define a pipeline that accepts a http request and responds with an XML serialisation of the request.

Defining an XPE/XML pipeline

To define our first pipeline 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 within the xpipedef.xml file 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.

The following illustrates the XPE pipeline we have now defined:

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, view full documentation for the http source component.

Or you may access the Online manual itself.

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

xar/META-INF/urlPattern.xml

xpipedef.xml

xar.xml

You should notice that this pipeline contains no filter nodes. It is the simplest possible XPE pipeline, having a source and a sink node only.

Step 5 - 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/console url:

• http://localhost:8188/xpe/console

You should see a page similar to:

select deploy application from the left hand menu.You should now see the application deployment dialog:

Now 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 successfull deployment page:

Step 6 - 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 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 (17e66c97d24bac9) - 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.