Configuration options for streaming
Saxon attempts streamed evaluation only if it is explicitly requested. Streaming may be requested in a number of ways:
-
By use of XSLT 3.0 language constructs that request streaming, for example the xsl:source-document instruction with attribute
streamable="yes"
, or by specifyingstreamable="yes"
on xsl:mode or xsl:accumulator. -
By use of a Saxon extension that requests streaming, for example saxon:stream.
-
By setting the option
-stream:on
in the XQuery command line, or the equivalent API option (for example, in s9api, XQueryCompiler.setStreaming(true)).
There are three configuration options that control how these requests for streaming are interpreted:
- The configuration property STREAMABILITY may be set to one of the values "off" or "standard". (Releases prior to 9.8 supported a third option, "extended".) With a licensed Saxon-EE configuration, the default is "standard", which means that streaming will happen if it is requested and if it is feasible. Setting the value to "off" causes Saxon to behave as if there is no Saxon-EE license: that is, requests for streaming are effectively ignored, and the stylesheet is executed in a non-streaming manner (which means that processing of a large document may fail if there is insufficient memory).
- The configuration property STREAMING_FALLBACK determines what
Saxon does when streaming is requested, and a construct is found that is deemed
non-streamable. This is a boolean option. If it is set to
true
, Saxon attempts a non-streaming implementation of the relevant construct. If sufficient memory is available for a non-streaming evaluation, this should always give the same result as a streamed evaluation. When the option is set tofalse
(the default), the presence of a construct that is deemed non-streamable causes a static (compile-time) error. - The configuration property STRICT_STREAMABILITY
determines how closely Saxon's streamability analysis follows the rules in the
W3C specification. This is a boolean value (with the default
false
): the valuetrue
requests strict adherence to the W3C rules. In reality this option does not affect the rules that Saxon applies, rather it affects when they are applied. By default Saxon first performs all its usual compile-time optimizations to the expression tree, and then checks the final result for streamability. During the optimization process Saxon takes care to avoid replacing streamable constructs with non-streamable equivalents, but it may do the reverse. As a result, constructs that are not streamable according to the W3C rules may become streamable after optimization. (An example is the non-streamable expressionAUTHOR or EDITOR
, which Saxon rewrites in the streamable formexists(AUTHOR | EDITOR)
.) For interoperability, the W3C specification requires processors to provide a mode of operation in which the W3C streamability rules are enforced rigidly, and this is achieved by settingSTRICT_STREAMABILITY
totrue
. With this setting, Saxon checks the expression tree for streamability before doing any optimizations that change the tree.
When running from the command line these options can be set for example as
--streamability:off
or --streamingFallback:on
.