Saxonica.com

The saxon:stream() extension function

The simplest way to invoke the facility is using the saxon:stream() extension function. This function returns a deep copy of the sequence supplied in its first argument, using streaming-mode evaluation if it can. Streaming-mode evaluation is possible only if the first argument is a path expression conforming to certain rules, defined below.

This is supported only in Saxon-SA (though the stylesheet does not need to be schema-aware).

In XSLT an alternative way of invoking the facility is by using an <xsl:copy-of> instruction with the special attribute saxon:read-once="yes". In XQuery the same effect can be achieved using a pragma (# saxon:read-once #). The advantage of these mechanisms over the saxon:stream() extension function is that they do not compromise the portabilility of the code: it will still run, and in nearly all cases produce the same effect, with a processor that does not recognize these extensions.

A very simple way of using this technique is when making a selective copy of parts of a document. For example, the following code creates an output document containing all the footnote elements from the source document that have the attribute @type='endnote':

XSLT example


<xsl:template name="main">
  <footnotes>
    <xsl:sequence select="saxon:stream(doc('thesis.xml')//footnote[@type='endnote'])"
                  xmlns:saxon="http://saxon.sf.net/"/>
  </footnotes>
</xsl:template>

XQuery example


  <footnotes>{
     saxon:stream(doc('thesis.xml')//footnote[@type='endnote']) 
  }</footnotes>

To allow code to be written in a way that will still work with processors other than Saxon, the facility can also be invoked using extension attributes in XSLT, or pragmas in XQuery. Using this syntax, the previous examples can be written as:

XSLT example


<xsl:template name="main">
  <footnotes>
    <xsl:copy-of select="doc('thesis.xml')//footnote[@type='endnote']"
                   saxon:read-once="yes" xmlns:saxon="http://saxon.sf.net/"/>
  </footnotes>
</xsl:template>

XQuery example


  <footnotes>{
    (# saxon:stream #) {
       doc('thesis.xml')//footnote[@type='endnote']
    }   
  }</footnotes>

Note the restrictions below on the kind of predicate that may be used.

Next