Presents your 
XML E-NEWSLETTER for December 18, 2002

<------------------------------------------->

TRACK AND DEBUG XSL TEMPLATES WITH THE MESSAGE ELEMENT

Managing and debugging XSL templates and processes can be difficult and
tricky. In many instances, documents fail during the translation process
and you have little information to point you in the right direction. 
XSL provides a mechanism you can use for communicating messages back to the
translation engine.

FRAMING THE PROBLEM

Let's start by examining a simple XML document. LISTING 1 shows a very
simplified order that contains a few items. We're going to create an XSL
template that performs the trivial function of stripping the <Items> 
tag out of this template:

Listing 1: order.xml
<Order>
  <Items>
    <Item>
      <SKU>19723</SKU>
      <Description>Mechawidget Flange</Description>
    </Item>
    <Item>
      <SKU>87123</SKU>
      <Description>Hydrafluant Magnet</Description>
    </Item>
    <Item>
      <SKU>662354</SKU>
      <Description>Generic Rubber Seal</Description>
    </Item>
    <Item>
      <SKU>967623</SKU>
      <Description>Fluxating Plasmatron</Description>
    </Item>
  </Items>
</Order>

The basic XSL document is shown in LISTING 2. You will notice that
there's a problem with this document. It's not going to provide the 
desired results.

Listing 2: order.xsl
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml"/>
  <xsl:template match="/Order">
    <NewOrder>
      <xsl:apply-templates/>
    </NewOrder>
  </xsl:template>
  <xsl:template match="Items/item">
    <Item>
      <SKU><xsl:value-of select="./SKU" /></SKU>
      <Description><xsl:value-of select="./Description" 
/></Description>
    </Item>
  </xsl:template>
</xsl:stylesheet>

TRACING THE PROBLEM

In many cases, you can catch the problem as it occurs or by skimming the
XSL template. If you are observant, you might find it quickly. Or you
might spend days trying to figure out what's happening and why it 
doesn't do what you're expecting.

Another solution is to use the <xsl:message> element. This simple
element can provide the equivalent of printf debugging statements in 
your XSL documents. By incorporating <xsl:message>, you can gain insight
into the flow of your document.

A message can be delivered by enclosing it in the <xsl:message> tags.
For example, a Hello World message might look like this:

<xsl:message>Hello World!</xsl:message>

We can now incorporate messages into our XSL document and see that the
flow doesn't go the way we expected. LISTING 3 shows our revised
problematic XSL document with messages added:

Listing 3: order2.xsl
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml"/>
  <xsl:template match="/Order">
    <xsl:message>Found order element</xsl:message>
    <NewOrder>
      <xsl:message>Applying templates below Order element</xsl:message>
      <xsl:apply-templates/>
    </NewOrder>
  </xsl:template>
  <xsl:template match="Items/item">
    <xsl:message>Processing item with SKU <xsl:value-of select="./SKU"
/></xsl:message>
<Item>
      <SKU><xsl:value-of select="./SKU" /></SKU>
      <Description><xsl:value-of select="./Description" 
/></Description>
    </Item>
  </xsl:template>
</xsl:stylesheet>

Now when we run the translation process, we'll see the output of the
messages. In this case, they will look like this:

file:///C:/order.xsl; Line #6; Column #18; Found order element
file:///C:/order.xsl; Line #8; Column #20; Applying templates below
Order element

Now we can see that the flow goes from "Applying templates" to the
<xsl:apply-templates/> tag, but our following template doesn't match 
for some reason. The match should be Items/Item instead of Items/item.

TERMINATION

The <xsl:message> tag can do more than just show you what's happening in
your translation process. It can also allow you to terminate the process
if something isn't quite right. For example, imagine if the SKUs in the
above example are supposed to be 5 digits or less. When we run the
process, we want it to alert us and terminate if there's a SKU that 
doesn't meet this requirement.

Using the terminate attribute of the <xsl:message> element, we can
instruct the processor to stop processing once the associated message is
displayed. LISTING 4 shows an example of how to handle this scenario:

Listing 4: stoporder.xsl
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml"/>
  <xsl:template match="/Order">
    <xsl:message>Found order element</xsl:message>
    <NewOrder>
      <xsl:message>Applying templates below Order element</xsl:message>
      <xsl:apply-templates/>
    </NewOrder>
  </xsl:template>
  <xsl:template match="Items/Item">
    <xsl:message>Processing item with SKU <xsl:value-of select="./SKU"
/></xsl:message>
    <xsl:if test="string-length(./SKU)>5">
    <xsl:message terminate="yes">terminating. sku is too
long</xsl:message>    
    </xsl:if>
    <Item>
      <SKU><xsl:value-of select="./SKU" /></SKU>
      <Description><xsl:value-of select="./Description" 
/></Description>
    </Item>
  </xsl:template>
</xsl:stylesheet>

This time when we run the process, we'll see an output similar to the
following:

file:///C:/order.xsl; Line #6; Column #18; Found order element
file:///C:/order.xsl; Line #8; Column #20; Applying templates below Order element
file:///C:/order.xsl; Line #14; Column #18; Processing item with SKU 19723
file:///C:/order.xsl; Line #14; Column #18; Processing item with SKU 87123
file:///C:/order.xsl; Line #14; Column #18; Processing item with SKU 662354
file:///C:/order.xsl; Line #16; Column #35; terminating. SKU is too long

As you can see, we've corrected the original error, and each item SKU is
shown as it's processed. You can also see that SKU 662354 is six digits,
which is one too many. The test within our XSL document detects this
problem, displays a message communicating the problem, and terminates the
processing. In this case, the output document is not created.

Brian Schaffner is a senior consultant for Fujitsu Consulting. He
provides architecture, design, and development support for Fujitsu's 
Telcom360 group.

---------------------------------------