# 13. XML Support

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
XML Support
Rendering SQL Queries as XML (FOR XML Clause)
XML Composing Functions in SQL Statements (SQLX)
Virtuoso XML Services
Querying Stored XML Data
Using UpdateGrams to Modify Data
XML Templates
XML DTD and XML Schemas
XQuery 1.0 Support
XSLT Transformation
Namespaces The <xsl:output> Tag External Parameters in XSLT Stylesheets Functions XSLT Examples XPath Function Extensions for XSLT Status Of XSLT And XPath Implementation
XMLType
Changing XML entities in DOM style

## 13.9. XSLT Transformation

Virtuoso implements XSLT 1.0 transformations as SQL callable functions. In general, Virtuoso's XSLT processor follows the XSLT 1.0 standard as far as possible without loss of database-related functionality. The most important difference is in error handling. While XSLT rules assume that almost any error must be recovered, Virtuoso will stop the transformation in case of data access error or in case of serious arithmetic error, such as divide by zero. This is due to the greater complexity of the Virtuoso XSLT processor's environment. Standalone processors generally accept a set of files as input parameters, the only output is the resulting transformation as a file, and all configuration parameters are listed on the command line. Virtuoso's XSLT processor may retrieve both data and stylesheets from local filesystems, local tables, remote datasources, or the Web. Parameters of the stylesheet transformation may be prepared by complicated Virtuoso PL procedures and so on. Plain XSLT processors may continue producing "dirty" output; Virtuoso's processor will stop upon encountering serious in order to produce helpful error diagnostics.

Another important difference is that Virtuoso has one processor for XSLT, XPath and XQuery. The user will find this convenient because an application may use XSLT-specific functions in XPath expressions, XQuery functions in XSLT, and so on. If extension functions are defined for the XSLT processor, they may also be used in XPath and XQuery expressions without any additional operations. One caveat is that this may invalidate some rules related to the document order of nodes in node-sets. Both the XPath 1.0 and XSLT 1.0 standards say that some functions must process the node that is first in document order from a given node-set. In such cases Virtuoso's processor will process the first node found in the node-set, regardless of whether it is actually the first in document order or not. This is done because the old XPath rule is nonsensical if nodes of the node-set are retrieved from more than one document or are created in the query. The processor follows the old rule for 99% of real expressions. Specifically, it fully matches the standards' rules for all XPath expressions that are free of reverse-order axes and non-standard functions.

### 13.9.1. Namespaces

In the following the xsl: namespace prefix is used to mean "http://www.w3.org/XSL/Transform/1.0". In fact all namespace URI's beginning with "http://www.w3.org/XSL/Transform" are considered as the XSLT namespace. The namespaces "http://www.w3.org/1999/XSL/Transform" and "http://www.w3.org/TR/WD-xsl" are recognized as synonymous. No other namespace URI's have special significance.

### 13.9.2. The <xsl:output> Tag

The Virtuoso XSLT processor recognizes and verifies the <xsl:output> tag. The only <xsl:output> attributes that are used are the method, encoding, omit-xml-declaration, media-type, doctype-public doctype-system and indent. The processor output is created in the character set that is in effect for the client or the one specified by encoding.

The SQL function xml_tree_doc_media_type() returns the media type in effect for the result of the xslt() function based on the xsl:output media-type and method attributes of the stylesheet applied. This method is also used for producing FOR XML AUTO WebDAV resources for HTTP reply generation.

### 13.9.3. External Parameters in XSLT Stylesheets

The XSLT 1.0 standard specifies that parameters may be passed to the XSLT processor from its environment in order to control data transformation, but the details are implementation-specific. Virtuoso's XSLT Processor will accept default values for global parameters from the optional third argument of the xslt() Virtuoso PL function. This argument, if specified, must be a vector of parameter names and values of the form vector(name1, value1,... nameN, valueN), where name1 ... nameN must be of type varchar, and value1 ... valueN may be of any Virtuoso datatype, but may not be null. If a parameter has a null value specified, it is removed from the vector without any further processing. After removal of null values, duplicate names are eliminated. If a name occurs more than once in the vector, only the last one will be retained.

When the XSLT Processor begins the transformation of the document, it creates two stacks of variables, one for global variables and one for local variables. Initially the stacks are empty. Then it prepares temporary indexes for all <xsl:key> elements; all future calls of key() function will return without any searches through the source document. Only after the processing of all keys of the stylesheet, the XSLT Processor pushes all parameters from the third argument of the xslt() function into the stack of local variables. Then, as described in the XSLT specification, it initializes top-level variables and parameters. For every <xsl:variable> or <xsl:param> element found at the top-level of the main stylesheet or at the top level of some imported stylesheet, the processor calculates the value and pushes the created variable into the stack of local variables. The <xsl:param> element is ignored if the specified name is already declared in the vector of parameters or in some stylesheet imported before. When all top-level variables and parameters are initialized, the content of the stack of local variables is moved into the stack of global variables, and the stack of local variables is made empty. During the rest of the XSLT transformation, these variables will be used as global variables. They may be temporarily shadowed by inner declarations of local variables - though not by declarations of local parameters - but they cannot be changed. Note that expressions for values of variables and parameters may contain calls of key() function, because temporary indexes are ready to use before the first such expression is calculated. Expressions of <xsl:key> elements may not refer to any parameters or variables, due to the same reason.

### 13.9.4. Functions

The xslt() Virtuoso/PL function applies a given stylesheet to a given source XML document and returns the transformed document. There is no restriction to what a VSP page can output, this is usually HTML but can be XML. The function http_xslt() allows a stylesheet to be applied to a whole output of an VSP page before it is sent to the user agent. Functions xslt_sheet() and xslt_stale() allow you to create and destroy a stylesheet dynamically. Function xmlupdate() is convenient for very simple "search-and replace" transformations.

### 13.9.5. XSLT Examples

This section covers some examples of applying XSLT to various stored data.

    create procedure xml_view_string (in _view varchar)
    {
      declare _body any;
      declare _pf varchar;
      _body := string_output ();
      http ('<document>', _body);
      _pf := concat ('DB.DBA.http_view_', _view);
      call (_pf) (_body);
      http ('</document>', _body);

      return (string_output_string (_body));
    }

    create procedure xslt_view (in v varchar, in xst varchar)
    {

      declare str, r varchar;
      xslt_sheet (xst, xtree_doc (file_to_string (xst)));
      str := xml_view_string (v);
      r := xslt (xst, xtree_doc (str));
      declare str_out any;
      str_out := string_output ();
      http_value (r, 0, str_out);
      string_to_file ('xslt.out', string_output_string (str_out), 0);
    }

These functions will take the serialized text of an XML view created with CREATE XML VIEW, transform it with a stylesheet and store the result into a file.

The first function returns a string containing the text generated as the value of the XML view specified as argument. It calls the serialization function, which is DB.DBA.http_view_ + view name. This function writes the text into the string output stream passed to it. Note that the function wraps the text inside a <document> element in order to make it well-formed, since the view serialization function will emit multiple top-level elements, one for each selected row in the root table in the XML view.

The xslt_view() function first defines the style sheet, which it takes from a file in this case. The xslt_sheet() function is called with the name and root element of the parsed file.

The function next gets the string to process, parses it as XML, and converts the parse tree into an entity object. This is then passed to the xslt() function. The result is another entity object. This is finally serialized as XML text and written into the file xslt.out.

These examples show how to parse and serialize XML using varchars, string output streams and the entity data type.

The central points are:

- The XML entity object is a reference to a particular element of a parsed XML document, The underlying document is only visible through this reference. A string is converted into such a document and a reference to the document's root is returned by the

      xtree_doc (string)

  function. In previous versions of Virtuoso, the combination

      xml_tree_doc (xml_tree (string))

  was used for this purpose; this combination still works to maintain backwards compatibility, but using xtree_doc() is preferable.
- A string output is used to capture the serialization of data by the http_value() function. If the string output were not specified the data would be sent to the HTTP client directly, if we were running in an HTTP request context.

### 13.9.6. XPath Function Extensions for XSLT

Virtuoso provides a way to extend the abilities of the XSLT processor by creating user defined XPath functions. The functions xpf_extension() and xpf_extension_remove() allow addition and removal of XPath extension functions.

### 13.9.7. Status Of XSLT And XPath Implementation

Items marked with (*) are currently not implemented.

#### 13.9.7.1. XPath Axes

- ancestor::
- ancestor-or-self::
- attribute::
- child::
- descendant::
- descendant-or-self::
- following::
- following-sibling::
- namespace:: (*)
- parent::
- preceding::
- preceding-sibling::
- self::

#### 13.9.7.2. Node Functions

- number position()
- number count(node-set)
- string local-name(node-set?)
- string namespace-uri(node-set?)
- string name(node-set?)
- boolean lang(string)

#### 13.9.7.3. Node Set Functions

- node-set document(string, string?, integer?, name?, name?, string?)
- node-set document-literal(string, string?, integer?, name?, name?, string?)
- node-set id(object)
- node-set append(object, object, ..., object)

#### 13.9.7.4. String Functions

- string string(object?)
- string serialize(object?)
- string format-number(number, string, string?)
- string concat(object, object, ..., object)
- number string-length(string?)
- boolean contains(string, string)
- boolean text-contains(string, string)
- boolean starts-with(string, string)
- boolean ends-with(string, string)
- string substring(string, number, number?)
- string substring-before(string, string)
- string substring-after(string, string)
- string normalize-space(string?)
- string translate(string, string, string)
- string replace(string, string, string)

#### 13.9.7.5. Boolean Functions

- boolean boolean(object)
- boolean true()
- boolean false()
- boolean not(boolean)
- boolean and(boolean, boolean, ..., boolean)
- boolean or(boolean, boolean, ..., boolean)
- boolean some(name, boolean, node-set)
- boolean every(name, boolean, node-set)
- boolean function_available(name)

#### 13.9.7.6. Number Functions

- number number(object?)
- number floor(number)
- number ceiling(number)
- number round(number)
- number sum(number)
- number avg(number)
- number max(number)
- number min(number)

#### 13.9.7.7. XSLT-specific Functions

- current()
- function-available(string)
- unparsed-entity-uri(string)
- system-property(string)

#### 13.9.7.8. XSLT 1.0 Elements and Attributes

- xsl:apply-imports
- xsl:apply-templates
- xsl:attribute
- xsl:attribute-set (*)
- xsl:call-template
- xsl:choose
- xsl:comment
- xsl:copy
- xsl:copy-of
- xsl:decimal-format
- xsl:element
- xsl:fallback (*)
- xsl:for-each
- xsl:if
- xsl:import
- xsl:include
- xsl:key
- xsl:message
- xsl:namespace-alias
- xsl:number NOTE: formatting and level="any" is not implemented
- xsl:otherwise
- xsl:output
- xsl:param
- xsl:preserve-space (*)
- xsl:processing-instruction
- xsl:sort
- xsl:strip-space
- xsl:stylesheet
- xsl:template
- xsl:text
- xsl:transform (*) NOTE: use xsl:stylesheet instead
- xsl:value-of
- xsl:variable
- xsl:when
- xsl:with-param

Previous XQuery 1.0 Support | Chapter Contents | Next XMLType