XSPTutorial

Canonical XSP page

An XSP page is an XML page with the following requirements:

Usually you will also require further processing of the resulting page, with a stylesheet for instance, to transform the results of your code into a readable form for the viewer (typically to HTML).

You should remember that cocoon processing instructions act upon a whole document, then generate a result document, which will in turn be passed to the next cocoon processor, rather like a pipeline.

So, here is a minimal XSP page:

<?xml version="1.0"?>  
<?cocoon-process type="xsp"?>  
<?cocoon-process type="xslt"?>  
<?xml-stylesheet href="page-html.xsl" type="text/xsl"?>  

<xsp:page language="java" xmlns:xsp="http://www.apache.org/1999/XSP/Core">  
<xsp:logic>  
  static private int counter = 0;  
  private synchronized int count() {  
    return counter++;  
  }  
</xsp:logic>  

<page>
  <p>I've been requested <xsp:expr>count()</xsp:expr> times.</p>  
</page>  
</xsp:page>

Let's look at each part of this, one at a time:

<?xml version="1.0"?>

required for every XML page

<?cocoon-process type="xsp"?>

first process this page with the Cocoon XSP Processor

<?cocoon-process type="xslt"?>

then run the results through the XSLT processor

<?xml-stylesheet href="page-html.xsl" type="text/xsl"?>

This is the stylesheet that the XSLT processor should use

<xsp:page language="java" xmlns:xsp="http://www.apache.org/1999/XSP/Core">

This is required for an XSP page.

The document root must be xsp:page.

The language attribute is optional.

You can also specify optional Taglibs here by including their XML namespace references. You will definitely need at least the xmlns:xsp definition.

Other Taglib namespaces are available and should be added here as attributes... see Built-in Taglibs below.

<xsp:logic>
  static private int counter = 0;  
  private synchronized int count() {  
    return counter++;  
  }  
</xsp:logic>

<xsp:logic> tags specify definitions of things in the language that is used on this XSP page... usually functions and class-wide variables.
In this case, we are using Java.

<page>  
  <p>I've been requested <xsp:expr>count()</xsp:expr> times.</p>  
</page>

Here is the bulk of the page content specified as general XML.

The first element that you place here (in this case <page>) will become the document root element of the xml document that will be generated after the XSP processor has finished.

The <xsp:expr>count()</xsp:expr> element here is saying “call the function 'count()' and convert the result into a text node”. <xsp:expr> is used wherever you need to insert live data into the output document.

The output of the XSP processor will produce the following page (obviously the value of count() will change over time:

<?xml version="1.0"?>  
<?cocoon-process type="xslt"?>  
<?xml-stylesheet href="page-html.xsl" type="text/xsl"?>  
<page>  
  <p>I've been requested 0 times.</p>  
</page>

3 types of XSP pages

Embedded Logic

In this situation, we place the code directly in the XML page. This is pretty bad style and only really useful for trivial examples, but it's useful to run through what happens when an XSP page “does stuff”.

So what happens?

First, the XSP processor parses the XML file and turns the whole page into an XSP servlet. Sounds strange, but true? All of the static XML gets turned into Java commands that insert XML elements, attributes and entities into a DOM tree. It can be very educational to take a look through your servlet engine's “repository” directory: there you will usually find a java file corresponding to each XSP page. You'll be surprised to see just how much a simple XSP page expands out to...

So, the static XML elements turn into function calls with constant parameters, whereas the dynamic logic bits (the whole point of this) get turned into... you guessed it... function calls with variables as parameters.

In this scenario, the XML page IS an XSP page... it has the canonical format for an XSP page. The root element of an XSP page must be xsp:page. The resulting XML page is then transformed using the relevant XSLT stylesheet, which (in this case) results in a HTML page.

Included logicsheet

This is a much more preferable way to be working, whereby parts of the original XML document that are matched by the stylesheet are replaced with sections of logic code.

In this scenario, an XSP page is generated from the original XML page, rather than the original XML page BEING an XSP page.

This is an example of a “logicsheet”. The original XML file's elements are replaced with pieces of logic (or plain ole XML, as needed). The transformation is done by an XSL stylesheet, the results of which are pieces of XSP logic or expressions.

In the diagram we see that the <item/> element will be substituted with the contents of the <template match="item></template> element. In this case, it's an <xsp:expr></xsp:expr> element which will presumably contain some kind of Java code, which, when executed will insert a text node into the XML result tree.

More importantly than the specific contents of the page, once again it is important that the root element of the resulting XSP page is an <xsp:page> element.

By this stage, the result of this transformation (produced by the logicsheet) is a canonical XSP page. This will then be “executed” and the result will be an XML page, with all the variable bits replaced with actual values. Once again, the XSL stylesheet transforms the final outcome into a HTML page.

XSP page with taglib logicsheet

In this instance we are could be dealing with either of the two previous scenarios, the only difference is where the logicsheet lies. The taglibs are central libraries that can be referred to from anywhere within an XSP page. The most important aspect of the taglib is that it has an XML namespace declaration, declared in the original logicsheet, and matched in the <xsp:page> xmlns attribute.

A namespace declaration is a URI (usually, something like: “http://www.suranyami.com/MyImportantLibrary"). Apparently, there doesn't actually have to be anything at that address... just that it's a uniquely identifiable name.

This namespace declaration then matches to the logicsheet referred to in the cocoon.properties file. Here is a typical situation:

XSP page

<xsp:page xmlns:**utilities**="_http://www.suranyami.com/myUtilities_">  
...  
</xsp:page>

#### Logicsheet file

```xml
<xsl:stylesheet version="1.0" xmlns:**utilities**="_http://www.suranyami.com/myUtilities_">  
...  
</xsl:stylesheet>

cocoon.properties

processor.xsp.logicsheet.**utilities**.java = file:///home/dayv/myUtilities.xsl

XSP core tags & meanings

<xsp:page>

The root level element of an XSP page.

<xsp:logic>

Defines a section of code such as functions and variable declarations.

<xsp:expr>

Inserts a text node into the output tree of the XML file.

2001-12-06 David Parry

Thanks to The Wayback Machine for having a copy of this. My blog stats were showing that people still referred to this. Sorry it was missing for so long!

Discuss...