SAXONICA

Saxon Documentation
Full Contents
About Saxon
Changes in this Release
Notices
Using XSLT 2.0
Using XQuery
Handling Source Documents
| Handling Source Documents
| Source Documents on the Command Line
| Collections
| Building a Source Document from an application
| Preloading shared reference documents
| Writing input filters
| XInclude processing
| Saxon and XML 1.1
| JAXP Source Types
| Third-party Object Models: DOM, JDOM, XOM, and DOM4J
| Choosing a Tree Model
| The PTree File Format
| Validation of Source Documents
| Whitespace Stripping in Source Documents
» | Streaming of Large Documents
| Document Projection
XML Schema Processing
XPath API for Java
Saxon on .NET
Extensibility
Saxon Extensions
Sample Saxon Applications
The Saxon SQL Extension
XSLT Elements
XPath 2.0 Expression Syntax
Function Library
Standards Conformance

# 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