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"> </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:
2.4 Data Output
The data output produces the result of the transformation. The following XML is
the result of the above transformation:
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>