xsl:source-document
Used to initiate streamed or unstreamed processing of a source document.
Category: instruction
Content: sequence-constructor
Permitted parent elements:
any XSLT element whose content model is
sequence-constructor; any literal result element
Attributes
|
| The URI of a source document. It can be written as an attribute value template if the URI is not known statically. |
|
| Used to request streamed processing
(the default is |
|
| Defines the set of accumulators that are applicable to the document. |
|
| Requests strict or lax validation of the contents of the document against the element declaration of its top-level element. |
|
| Requests validation of the source document against a specified XSD type. The value will typically be a user-defined complex type defined in an imported schema. |
|
| Controls whether DTD validation takes place. For details see saxon:dtd-validation. |
|
| Controls whether attribute defaults defined in the schema or DTD are expanded. For details see saxon:expand-attribute-defaults. |
|
| Used to enable line numbering for the document being read. For details see saxon:line-numbering. |
|
| Used to specify whitespace stripping: |
|
| Controls whether XInclude processing takes place. For details see saxon:xinclude. |
Saxon availability
Available in XSLT 3.0. From Saxon 9.8, available in all editions. Implemented in Saxon-EE since Saxon 9.7. Available for all platforms.
Notes on the Saxon implementation
The xsl:source-document instruction (used with the attribute
streamable="yes") replaces the xsl:stream instruction from
earlier drafts of the XSLT 3.0 specification. It first became available since Saxon
9.7.0.8, in Saxon-EE only (with XSLT 3.0 enabled), and becomes fully available
in all Saxon editions from 9.8 (but streaming requires Saxon-EE).
If streaming is requested and the expression cannot be evaluated in streaming mode, execution fails, unless the configuration property STREAMING_FALLBACK is set, in which case it is executed in non-streaming mode, after issuing a warning.
Details
The body of the instruction is a sequence constructor, which is evaluated with the root node of the selected document as the context node. For streaming to work, this must be written as a streamable sequence constructor. Expressed very informally, this means it must only make downward selections in the document, and no instruction or expression may make more than one downward selection. The examples in the W3C specification illustrate some of the possibilities; these examples all work with Saxon.
Quite apart from its use with streaming,
in comparison with the doc and document functions, the instruction
gives more control, for example over schema validation and the use of accumulators.
Some of the things that the instruction might do are:
-
Compute an aggregate such as a total or average (see the example below).
-
Initiate processing of the document using template rules, by calling xsl:apply-templates using a streamable mode.
-
Iterate over the contents of the document using xsl:for-each or (if there is a need to "remember" information from one element to the next) using xsl:iterate.
-
Perform grouping of the document contents using xsl:for-each-group. Saxon only has limited ability to do streamed grouping, but simple cases should work. It is necessary to use one of the attributes
group-adjacent,group-starting-with, orgroup-ending-with, and to use the new XSLT 3.0 binding variables for current group and current-grouping-key, rather than the XSLT 2.0 function.
For more details on streaming, see Streaming XML documents.
Examples
Example 1
A simple example:
<xsl:source-document streamable="yes" href="transactions.xml"> <out><xsl:value-of select="sum(*/transaction/value)"/></out> </xsl:source-document>Example 2
See further examples in the W3C specification; these examples all work with Saxon 9.5 onwards.