XSLT and JAXP Processors

1. Introduction

XSLT is a language for transforming XML documents into other XML documents. PresentationServer uses XSLT extensively as its main language to process XML documents.

PresentationServer ships with multiple implementations of XSLT:

  • Xalan 2.5.1 Interpreter
  • Xalan 2.5.1 Compiler (XSLTC)
  • Saxon 6.5.2
  • Saxon 8.1.1 (supporting a large subset of XSLT 2.0)

Additionally, PresentationServer can use any Java API for XML Processing (JAXP) compliant transformer.

2. Usage

Instantiate the XSLT Processor with a p:processor declaration. The following URIs are supported:

Processor Name Language Implementation
oxf:xslt XSLT 2.0 Saxon 8.1.1
oxf:xalan XSLT 1.0 Xalan 2.5.1 Interpreter
oxf:xsltc XSLT 1.0 Xalan 2.5.1 Compiler
oxf:saxon XSLT 1.0 Saxon 6.5.2
oxf:saxon8 XSLT 2.0 Saxon 8.1.1
oxf:generic-xslt-1.0 XSLT 1.0 Any JAXP (TrAX) XSLT 1.0 transformer
oxf:generic-xslt-2.0 XSLT 2.0 Any JAXP (TrAX) XSLT 2.0 transformer
oxf:xslt-1.0 XSLT 1.0 Default JAXP (TrAX) XSLT 1.0 transformer (currently Xalan)
oxf:xslt-2.0 XSLT 2.0 Default JAXP (TrAX) XSLT 2.0 transformer (currently Saxon 8)
oxf:trax Any Any JAXP (TrAX) transformer

transformer input An input containing a specific concrete TransformerFactory class.
config input The stylesheet
data input The document to which the stylesheet is applied
data output The result of the transformation
user-defined inputs The processor may support user-defined inputs

2.1 Transformer Input

The transformer is mandatory only when using the oxf:generic-xslt-1.0, oxf:generic-xslt-2.0 or the oxf:trax processor URI. It is implied otherwise.

This input points to a specific concrete subclass of TransformerFactory . For example, you can use the TrAX transformer to interface PresentationServer with a new hypothetical transformer (MyTrans):

  <p:processor name="oxf:trax" xmlns:p="http://www.orbeon.com/oxf/pipeline">
  <p:input name="transformer">
  <config>
  <class>com.mytrans.TransformerFactoryImpl</class>
  </config>
  </p:input>
  <p:input name="config">
  <mytrans>
...
  </mytrans>
  </p:input>
  <p:input name="data">
  <document>
...
  </document>
  </p:input>
  <p:output name="data" id="mytrans"/>
  </p:processor>

2.2 Config Input

The configuration input contains a stylesheet. The following example shows a simple XSLT stylesheet:

  <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/">
  <new-root>
  <xsl:value-of select="/root/a"/>
  <xsl:value-of select="/root/b"/>
  </new-root>
  </xsl:template>
  </xsl:stylesheet>

2.3 Data Input

The data input contains the source XML document. The example below works with the stylesheet shown above:

  <root>
  <a>a</a>
  <b>b</b>
  </root>

2.4 Data Output

The data output produces the result of the transformation. The following XML is the result of the above transformation:

  <new-root>ab</new-root>

2.5 User-Defined Inputs

XSLT transformers support reading optional user-defined inputs through the XSLT and XPath document() and doc() functions. For example:

  <p:processor name="oxf:xslt" xmlns:p="http://www.orbeon.com/oxf/pipeline">
  <p:input name="config">
  <address-book xsl:version="2.0">
  <xsl:variable name="document-1" select="doc('file:/document-1.xml')" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"/>
  <xsl:variable name="document-2" select="doc('input:my-input')" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"/>
  <!-- ... -->
  </address-book>
  </p:input>
  <p:input name="data" href="#some-id"/>
  <p:input name="my-input" href="#some-other-id"/>
  <p:output name="data" id="address-book"/>
  </p:processor>

In this example, the XPath expression doc('file:/document-1.xml') instructs the XSLT transformer to read the document stored at oxf:/document-1.xml and make it accessible through the variable named document-1. This is standard XSLT and XPath 2.0.

The second variable, document-2, is assigned using a similar XPath expression, but it uses a URI with a particular syntax: it starts with the scheme input:. This instructs the XSLT transformer to read the processor input called my-input. This input is connected to the XSLT processor with <p:input name="my-input" href="#some-other-id"/>. In this case, it is up to the user of the XSLT processor to connect additional inputs as she sees fit, as long as their names don't conflit with mandatory input and output names.

3. Passing Parameters to XSLT Stylesheets

XSLT supports xsl:param elements at the top level of a stylesheet. They allow passing parameters to the stylesheet, without modifying the stylesheet itself. With API such as JAXP, a programmer can associate values to those parameters, making them available to the stylesheet during execution.

XPL does not have a particular mechanism to set such stylesheet parameters, but a very simple workaround allows setting them. Assume you have a stylesheet with a start parameter, in a file called my-stylesheet.xsl:

  <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:param name="start" select="'a1'"/>
  <!-- ... -->
  </xsl:transform>

To set the start parameter with XPL, simply encapsulate the my-stylesheet.xsl stylesheet as follows:

  <p:processor name="oxf:xslt" xmlns:p="http://www.orbeon.com/oxf/pipeline">
  <p:input name="data" href="#stylesheet-input"/>
  <p:input name="config">
  <xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="my-stylesheet.xsl"/>
  <xsl:param name="start" select="'a2'"/>
  </xsl:stylesheet>
  </p:input>
  <p:output name="data" id="stylesheet-output"/>
  </p:processor>

The rules of XSLT's import statement will make sure that the imported stylesheet, my-stylesheet.xsl, receives the start parameter with the value "a2", as overridden in the importing stylesheet. Of course, the value does not have to be static, it can be computed dynamically as well.

4. Streaming Transformations for XML (STX)

Streaming Transformations for XML (STX) is a one-pass transformation language for XML documents that builds on the Simple API for XML (SAX). STX is intended as a high-speed, low memory consumption alternative to XSLT. Since it does not require the construction of an in-memory tree, it is suitable for use in resource constrained scenarios.

PresentationServer uses Joost to implement a STX transformer. Its usage is similar to an XSLT transformer, using the processor URI oxf:stx. This example demonstrates a simple STX transformation.

  <p:processor name="oxf:stx" xmlns:p="http://www.orbeon.com/oxf/pipeline">
  <p:input name="data" href="#source"/>
  <p:input name="config">
  <stx:transform version="1.0" pass-through="all" strip-space="yes" xmlns:stx="http://stx.sourceforge.net/2002/ns"></stx:transform>
  </p:input>
  <p:input name="data" href="#document"/>
  <p:output name="data" id="result"/>
  </p:processor>