Example: XSLT Server Extension

The XSLT server extension, written in Java, is designed to perform XSLT transformations on XML documents in the Tamino database. Database queries can extract the input XML document(s) and the XSLT stylesheet from Tamino, and the resulting document can be redirected back to the client or written to another collection within the same Tamino database. There are several configuration options available to control the behavior of the XSLT server extension.

The Tamino kit includes sample files that you can use for testing the server extension. They are available under the Tamino installation directory Examples/Server Extension/Java_Query_XSLT in the following subdirectories:

examples

Contains the sample schemas, input data and XSLT stylesheets;

config

Contains the configuration schema and sample configurations for Saxon and Xalan;

src

Contains the source code (Java), Install.xml, internal interface HTML documentation for the server extension and the prebuilt X-Tension package file (sxp).

The following sections are available:

• Requirements

• Known Limitations

• Installation

• Query Functions for Transformation

• Administrative Issues

• A Simple Transformation Example

Requirements

Known Limitations

The known limitations in the current implementation of the XSLT server extension are listed here:

• There is currently no mechanism for maintaining cache consistency if the XSLT stylesheet is changed in the Tamino database. This could become an issue if you are developing a stylesheet in the database. In this case the cache should be turned off.

Installation

The JAR files previously mentioned in the Requirements section, namely jaxp.jar and the XSLT processor, must be added to the class path before installing the XSLT server extension software package. The section Configuration describes how to select the XSLT processor of your choice. The XSLT server extension is contained in the package XSLT.sxp. Refer to the section Installing a Tamino Server Extension for information about installing server extensions and adding JAR files to the Java class path.

Query Functions for Transformation

The XSLT server extension has two separate query functions to perform XSLT transformations on XML data in Tamino. Both of them add wrapper elements to the input data and the result document. These wrapper elements are fully configurable through the SXS-Configuration document, and also through the run-time configuration parameters input_wrapper and result_wrapper. The default values are "XSLT_input" and "XSLT_result". If these parameter values are empty, no input or result wrapper is applied before or after the transformation, respectively. If an input wrapper is applied, thus adding a new root element, the result of the input query expression passed as the first argument (see below) does not have to be a single document; it may consist of zero or more documents. Furthermore, note that a stylesheet may require some adaptation if an input wrapper is being applied.

The media-type attribute of the xsl:output element in the stylesheet can be used to control the value of the content-type HTTP header that is returned to the client.

transform

This query function performs an XSLT transformation on an XML document extracted from a Tamino collection using an XSLT stylesheet queried from another collection. The result is returned to the client.

The following parameters are provided:

Usage of this function is illustrated in the section A Simple Transformation Example.

Administrative Issues

This section provides information on administrative issues involved with using the XSLT server extension.

• Storing Stylesheets

• Configuration

• Cache Management

Storing Stylesheets

There are two strategies for loading stylesheets:

• Load them into the collection ino:etc without providing a schema;

• Define a schema, for instance by using the enclosed schema file xsl_stylesheet.tsd. This file defines a doctype named xsl:stylesheet in the collection stylesheet.

Configuration

A Tamino SXS server extension query function is provided in order to manage the configuration of the XSLT server extension in conjunction with an SXS-Configuration XML document inside Tamino.

Syntax:

configuration (configkey, configvalue)

For more information on the syntax, please refer to the section Query Function Call Syntax.

cache_state

ON/OFF

cache_size

1 - 255

transformer_factory

Class Package

show

(ignored)

refresh

(ignored)

update

ON/OFF

input_wrapper

string

result_wrapper

string

The XML document returned by configuration("show","") is as follows:

...
<xql:result>
    <XSLT>
        <configuration>
            <show>
                <value name="cache_state">ON</value> 
                <value name="cache_size">128</value> 
                <value name="transformer_factory">com.icl.saxon.TransformerFactoryImpl</value> 
                <value name="input_wrapper">XSLT_input</value> 
                <value name="result_wrapper">XSLT_result</value> 
                <value name="update">ON</value>                           
            </show>
        </configuration>
    </XSLT>
</xql:result>
...

Based on the included schema file SXS-Configuration.tsd, a collection named SXS-Configuration (containing a single doctype "SXS-Configuration") can be defined.

The following is an example of an "SXS-Configuration" document:

<SXS-Configuration name="XSLT">
    <value name="cache_state">ON</value>
    <value name="cache_size">128</value>
    <value name="transformer_factory">com.icl.saxon.TransformerFactoryImpl</value>
    <value name="input_wrapper">myOwnInput</value>
    <value name="result_wrapper">myOwnResult</value>
    <value name="update">ON</value>                           
</SXS-Configuration>

Sample configuration documents for use with Saxon (default) and Xalan are enclosed in this package:

• SXS-Configuration_Saxon.xml

• SXS-Configuration_Xalan.xml

Cache Management

The XSLT server extension provides a Tamino SXS server extension query function in order to manage the stylesheet cache.

Syntax:

cache (operation)

For more information on the syntax, please refer to the section Query Function Call Syntax.

show

clear

delete=cache_key

The following shows a typical XML document returned by the cache("show") operation:

...
<xql:result>
   <XSLT>
      <cache>
         <show_cache>
            <cache_entries>
               <entry key="ino:etc/xsl:stylesheet[@ino:id=12]">
                  <value name="transformer_factory">com.icl.saxon.TransformerFactoryImpl</value> 
                  <value name="loaded">Mon Sep 17 04:12:16 EDT 2003</value>
                  <value name="last_used">Tues Sep 20 09:32:47 EDT 2003</value>
                  <value name="usage_count">19</value>
               </entry>
               <entry key="ino:etc/xsl:stylesheet[@ino:docname='mytransform']">
                  <value name="transformer_factory">com.icl.saxon.TransformerFactoryImpl</value> 
                  <value name="loaded">Mon Sep 17 03:15:26 EDT 2003</value>
                  <value name="last_used">Weds Sep 21 10:22:57 EDT 2003</value>
                  <value name="usage_count">3</value>
               </entry>
            </cache_entries>
         </show_cache>
      </cache>
   </XSLT>
</xql:result>
...

A Simple Transformation Example

In order to provide some hands-on experience, the following section gives step-by-step instructions for performing a simple transformation. The following example documents are contained in this kit:

The name of the Tamino database used in this example is "MyDB".

To perform a simple transformation

1. Define the schema (NASCAR_Drivers.tsd) in the database.

2. Process the input data (NASCAR_Drivers.xml) into collection NASCAR_Drivers.

   Note:
   This file contains multiple documents.

3. Process the XSLT stylesheet (NASCAR_Drivers_to_XML.xsl) into the ino:etc collection for "MyDB". Note the "ino:id" for the processed document (ino:id=1 for this example).

4. Verify the existence of the following documents in the database:

   http://localhost/tamino/MyDB/NASCAR_Drivers?_xql=NASCAR_Drivers
   http://localhost/tamino/MyDB/ino:etc?_xql=xsl:stylesheet[@ino:id=1]

5. Perform the transformation using X-Query:

   http://localhost/tamino/MyDB/NASCAR_Drivers?_xql=XSLT.transform (NASCAR_Drivers,'ino:etc','xsl:stylesheet[@ino:id=1]')

6. Perform the transformation using XQuery:

   http://localhost/tamino/MyDB/NASCAR_Drivers?_xquery= {?serialization method="XSLT.transform" parameter='ino:etc' parameter='xsl:stylesheet[@ino:id=1]'?} for $d in input()/NASCAR_Drivers return $d

where:

http://localhost/tamino/MyDB/NASCAR_Drivers

specifies the host, the database and the input data collection;

?_xql=

is the command verb to perform a query (the query expression follows after the = sign);

XSLT.transform

uses the transform query function contained in the XSLT server extension;

NASCAR_Drivers

is the query expression that extracts the input data from the collection;

'ino:etc'

is the collection that contains the XSLT stylesheet;

'xsl:stylesheet[@ino:id=1]'

is the query expression that extracts the stylesheet.