Saxon.Api

Class DocumentBuilder

Class DomDestination

Class DynamicContext

Class DynamicError

Class EmptyEnumerator

Class ExtensionFunctionCall

Class ExtensionFunctionDefinition

Class InvalidityHandlerWrapper

Class NamespaceConstant

Class NullDestination

Class Processor

Class QName

Class SchemaManager

Class SchemaValidator

Class Serializer

Class StandardLogger

Class StaticContext

Class StaticError

Class TextWriterDestination

Class XPathCompiler

Class XPathExecutable

Class XPathSelector

Class XQueryCompiler

Class XQueryEvaluator

Class XQueryExecutable

Class XdmAnyFunctionType

Class XdmAnyItemType

Class XdmAnyNodeType

Class XdmAtomicType

Class XdmAtomicValue

Class XdmDestination

  - Class TreeProtector

Class XdmEmptySequence

Class XdmFunctionItem

Class XdmItem

Class XdmItemType

Class XdmNode

Class XdmNodeKind

Class XdmSequenceType

Class XdmValue

Class XmlDestination

Class Xslt30Transformer

Class XsltCompiler

Class XsltExecutable

  - Class ParameterDetails

Class XsltPackage

Class XsltTransformer

Enum RecoveryPolicy

Enum SchemaValidationMode

Enum TreeModel

Enum WhitespacePolicy

Enum XdmAxis

Interface IInvalidityHandler

Interface IMessageListener

Interface IQueryResolver

Interface IResultDocumentHandler

Interface IXdmEnumerator

Interface IXmlLocation

Interface SchemaResolver

 

Saxon.Api
Class Xslt30Transformer 

public class Xslt30Transformer
implements object

An Xslt30Transformer represents a compiled and loaded stylesheet ready for execution. The Xslt30Transformer holds details of the dynamic evaluation context for the stylesheet.

The Xslt30Transformer differs from XsltTransformer in supporting new options for invoking a stylesheet, corresponding to facilities defined in the XSLT 3.0 specification. However, it is not confined to use with XSLT 3.0, and most of the new invocation facilities (for example, calling a stylesheet-defined function directly) work equally well with XSLT 2.0 and in some cases XSLT 1.0 stylesheets.

An Xslt30Transformer must not be used concurrently in multiple threads. It is safe, however, to reuse the object within a single thread to run the same stylesheet several times. Running the stylesheet does not change the context that has been established.

An Xslt30Transformer is always constructed by running the Load30 method of an XsltExecutable.

Unlike XsltTransformer, an Xslt30Transformer is not a Destination. To pipe the results of one transformation into another, the target should be an XsltTransfomer rather than an Xslt30Transformer.

Evaluation of an Xslt30Transformer proceeds in a number of phases:

  1. First, values may be supplied for stylesheet parameters and for the global context item. The global context item is used when initializing global variables. Unlike earlier transformation APIs, the global context item is quite independent of the "principal Source document".
  2. The stylesheet may now be repeatedly invoked. Each invocation takes one of three forms:
    1. Invocation by applying templates. In this case, the information required is (i) an initial mode (which defaults to the unnamed mode), (ii) an initial match sequence, which is any XDM value, which is used as the effective "select" expression of the implicit apply-templates call, and (iii) optionally, values for the tunnel and non-tunnel parameters defined on the templates that get invoked (equivalent to using xsl:with-param on the implicit apply-templates call).
    2. Invocation by calling a named template. In this case, the information required is (i) the name of the initial template (which defaults to "xsl:initial-template"), and (ii) optionally, values for the tunnel and non-tunnel parameters defined on the templates that get invoked (equivalent to using xsl:with-param on the implicit call-template instruction).
    3. Invocation by calling a named function. In this case, the information required is the sequence of arguments to the function call.
  3. Whichever invocation method is chosen, the result may either be returned directly, as an arbitrary XDM value, or it may effectively be wrapped in an XML document. If it is wrapped in an XML document, that document can be processed in a number of ways, for example it can be materialized as a tree in memory, it can be serialized as XML or HTML, or it can be subjected to further transformation.

Once the stylesheet has been invoked (using any of these methods), the values of the global context item and stylesheet parameters cannot be changed. If it is necessary to run another transformation with a different context item or different stylesheet parameters, a new Xslt30Transformer should be created from the original XsltExecutable.

@since 9.6

Property Summary
 XdmItem GlobalContextItem

Supply the context item to be used when evaluating global variables and parameters. The item to be used as the context item within the initializers of global variables and parameters. This argument can be null if no context item is to be supplied.

 net.sf.saxon.Controller GetUnderlyingController

Get the underlying Controller used to implement this XsltTransformer. This provides access to lower-level methods not otherwise available in the s9api interface. Note that classes and methods obtained by this route cannot be guaranteed stable from release to release.

 SchemaValidationMode SchemaValidationMode

The SchemaValidationMode to be used in this transformation, especially for documents loaded using the doc(), document(), or collection() functions.

 String BaseOutputURI

Get the base output URI.
 XmlResolver InputXmlResolver

The XmlResolver to be used at run-time to resolve and dereference URIs supplied to the doc() and document() functions.

 bool ssAssertionsEnabled

Ask whether assertions (xsl:assert instructions) have been enabled at run time.

 IMessageListener MessageListener Listener for messages output using <xsl:message>.

The caller may supply a message listener before calling Run; the processor will then invoke the listener once for each message generated during the transformation. Each message will be output as an object of type XdmNode representing a document node.

If no message listener is supplied by the caller, message information will be written to the standard error stream.

 StandardLogger TraceFunctionDestination Destination for output of messages using <trace()>.

If no message listener is supplied by the caller, message information will be written to the standard error stream.

 QName InitialMode

initial mode for the transformation. This is used if the stylesheet is subsequently invoked by any of the applyTemplates methods.

 
Method Summary
 void SetStylesheetParameters(System.Collections.Generic.Dictionary{Saxon.Api.QName,Saxon.Api.XdmValue} parameters)

Supply the values of global stylesheet variables and parameters.
 void SetInitialTemplateParameters(System.Collections.Generic.Dictionary{Saxon.Api.QName,Saxon.Api.XdmValue} parameters, System.Boolean tunnel)

Set parameters to be passed to the initial template. These are used whether the transformation is invoked by applying templates to an initial source item, or by invoking a named template. The parameters in question are the xsl:param elements appearing as children of the xsl:template element.

 void ApplyTemplates(System.IO.Stream input, XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied Source document, sending the results (wrapped in a document node) to a given Destination. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

 XdmValue ApplyTemplates(System.IO.Stream input, System.Uri baseUri)

Invoke the stylesheet by applying templates to a supplied Source document, returning the raw results as an XdmValue. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

 void ApplyTemplates(XdmValue selection, XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied input sequence, sending the results (wrapped in a document node) to a given Destination. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

 XdmValue ApplyTemplates(XdmValue selection)

Invoke the stylesheet by applying templates to a supplied input sequence, returning the raw results. as an XdmValue. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

 void CallTemplate(QName templateName, XmlDestination destination)

Invoke a transformation by calling a named template. The results of calling the template are wrapped in a document node, which is then sent to the specified destination. If #SetInitialTemplateParameters has been called, then the parameters supplied are made available to the called template (no error occurs if parameters are supplied that are not used).

 XdmValue CallTemplate(QName templateName)

Invoke a transformation by calling a named template. The results of calling the template are returned as a raw value, without wrapping in a document nnode or serializing.

 XdmValue CallFunction(QName function, Saxon.Api.XdmValue[] arguments)

Call a public user-defined function in the stylesheet.

 void CallFunction(QName function, Saxon.Api.XdmValue[] arguments, XmlDestination destination)

Call a public user-defined function in the stylesheet, wrapping the result in an XML document, and sending this document to a specified destination

 
Property Detail

GlobalContextItem

public XdmItem GlobalContextItem {get; set; }

Supply the context item to be used when evaluating global variables and parameters. The item to be used as the context item within the initializers of global variables and parameters. This argument can be null if no context item is to be supplied.

GetUnderlyingController

public net.sf.saxon.Controller GetUnderlyingController {get; }

Get the underlying Controller used to implement this XsltTransformer. This provides access to lower-level methods not otherwise available in the s9api interface. Note that classes and methods obtained by this route cannot be guaranteed stable from release to release.

SchemaValidationMode

public SchemaValidationMode SchemaValidationMode {get; set; }

The SchemaValidationMode to be used in this transformation, especially for documents loaded using the doc(), document(), or collection() functions.

BaseOutputURI

public String BaseOutputURI {get; set; }

Get the base output URI.

This returns the value set using the setter method. If no value has been set explicitly, then the method returns null if called before the transformation, or the computed default base output URI if called after the transformation.

The base output URI is used for resolving relative URIs in the href attribute of the xsl:result-document instruction.

Returns:
The base output URI

InputXmlResolver

public XmlResolver InputXmlResolver {get; set; }

The XmlResolver to be used at run-time to resolve and dereference URIs supplied to the doc() and document() functions.

ssAssertionsEnabled

public bool ssAssertionsEnabled {get; }

Ask whether assertions (xsl:assert instructions) have been enabled at run time.

By default they are disabled at compile time. If assertions are enabled at compile time, then by default they will also be enabled at run time; but they can be disabled at run time by specific request. At compile time, assertions can be enabled for some packages and disabled for others; at run-time, they can only be enabled or disabled globally.

Since 9.7

Returns:
true if assertions are enabled at run time

MessageListener

public IMessageListener MessageListener {get; set; }
Listener for messages output using <xsl:message>.

The caller may supply a message listener before calling Run; the processor will then invoke the listener once for each message generated during the transformation. Each message will be output as an object of type XdmNode representing a document node.

If no message listener is supplied by the caller, message information will be written to the standard error stream.

Each message is presented as an XML document node. Calling ToString() on the message object will usually generate an acceptable representation of the message.

When the <xsl:message> instruction specifies terminate="yes", the message is first notified using this interface, and then an exception is thrown which terminates the transformation.

TraceFunctionDestination

public StandardLogger TraceFunctionDestination {get; set; }
Destination for output of messages using <trace()>.

If no message listener is supplied by the caller, message information will be written to the standard error stream.

The supplied destination is ignored if a TraceListener is in use.

Since 9.6. Changed in 9.6 to use a StandardLogger

InitialMode

public QName InitialMode {get; set; }

initial mode for the transformation. This is used if the stylesheet is subsequently invoked by any of the applyTemplates methods.

The value may be the name of the initial mode, or null to indicate the default (unnamed) mode

Method Detail

SetStylesheetParameters

public void SetStylesheetParameters(System.Collections.Generic.Dictionary{Saxon.Api.QName,Saxon.Api.XdmValue} parameters)

Supply the values of global stylesheet variables and parameters.

Parameters:
parameters -
A Dictionary whose keys are QNames identifying global stylesheet parameters, and whose corresponding values are the values to be assigned to those parameters. If necessary the supplied values are converted to the declared type of the parameter. The contents of the supplied map are copied by this method, so subsequent changes to the map have no effect.

SetInitialTemplateParameters

public void SetInitialTemplateParameters(System.Collections.Generic.Dictionary{Saxon.Api.QName,Saxon.Api.XdmValue} parameters,
System.Boolean tunnel)

Set parameters to be passed to the initial template. These are used whether the transformation is invoked by applying templates to an initial source item, or by invoking a named template. The parameters in question are the xsl:param elements appearing as children of the xsl:template element.

The parameters are supplied in the form of a map; the key is a QName which must match the name of the parameter; the associated value is an XdmValue containing the value to be used for the parameter. If the initial template defines any required parameters, the map must include a corresponding value. If the initial template defines any parameters that are not present in the map, the default value is used. If the map contains any parameters that are not defined in the initial template, these values are silently ignored.

The supplied values are converted to the required type using the function conversion rules. If conversion is not possible, a run-time error occurs (not now, but later, when the transformation is actually run).

The XsltTransformer retains a reference to the supplied map, so parameters can be added or changed until the point where the transformation is run.

The XSLT 3.0 specification makes provision for supplying parameters to the initial template, as well as global stylesheet parameters. Although there is no similar provision in the XSLT 1.0 or 2.0 specifications, this method works for all stylesheets, regardless whether XSLT 3.0 is enabled or not.

Parameters:
parameters -
The parameters to be used for the initial template
tunnel -
true if these values are to be used for setting tunnel parameters; false if they are to be used for non-tunnel parameters

ApplyTemplates

public void ApplyTemplates(System.IO.Stream input,
XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied Source document, sending the results (wrapped in a document node) to a given Destination. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

Parameters:
input -
Input. The source document.To apply more than one transformation to the same source document, the source document tree can be pre-built using a DocumentBuilder.
destination -
Destination. the destination of the result document produced by wrapping the result of the apply-templates call in a document node. If the destination is a Serializer, then the serialization parameters set in the serializer are combined with those defined in the stylesheet (the parameters set in the serializer take precedence).

ApplyTemplates

public XdmValue ApplyTemplates(System.IO.Stream input,
System.Uri baseUri)

Invoke the stylesheet by applying templates to a supplied Source document, returning the raw results as an XdmValue. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

Parameters:
input -
Input. The source document
baseUri -
Base URI.
Returns:
XdmValue. The raw result of processing the supplied Source using the selected template rule, without wrapping the returned sequence in a document node

ApplyTemplates

public void ApplyTemplates(XdmValue selection,
XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied input sequence, sending the results (wrapped in a document node) to a given Destination. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

Parameters:
selection -
Selection. the initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates)
destination -
Destination. The destination of the result document produced by wrapping the result of the apply-templates call in a document node. If the destination is a Serializer, then the serialization parameters set in the serializer are combined with those defined in the stylesheet (the parameters set in the serializer take precedence).

ApplyTemplates

public XdmValue ApplyTemplates(XdmValue selection)

Invoke the stylesheet by applying templates to a supplied input sequence, returning the raw results. as an XdmValue. The invocation uses any initial mode set using #InitialMode, and any template parameters set using #SetInitialTemplateParameters.

Parameters:
selection -
Selection. selection the initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates)
Returns:
Xdmvalue. he raw result of applying templates to the supplied selection value, without wrapping in a document node or serializing the result. If there is more that one item in the selection, the result is the concatenation of the results of applying templates to each item in turn.

CallTemplate

public void CallTemplate(QName templateName,
XmlDestination destination)

Invoke a transformation by calling a named template. The results of calling the template are wrapped in a document node, which is then sent to the specified destination. If #SetInitialTemplateParameters has been called, then the parameters supplied are made available to the called template (no error occurs if parameters are supplied that are not used).

Parameters:
templateName -
The name of the initial template. This must match the name of a public named template in the stylesheet. If the value is null, the QName xsl:initial-template is used.
destination -
The destination of the result document produced by wrapping the result of the apply-templates call in a document node. If the destination is a Serializer, then the serialization parameters set in the serializer are combined with those defined in the stylesheet (the parameters set in the serializer take precedence).

CallTemplate

public XdmValue CallTemplate(QName templateName)

Invoke a transformation by calling a named template. The results of calling the template are returned as a raw value, without wrapping in a document nnode or serializing.

Parameters:
templateName -
the name of the initial temaplte. This must match the name of a public named template in the stylesheet. If the value is null, the QName xsl:initial-template is used.
Returns:
the raw results of the called template, without wrapping in a document node or serialization.

CallFunction

public XdmValue CallFunction(QName function,
Saxon.Api.XdmValue[] arguments)

Call a public user-defined function in the stylesheet.

Parameters:
function -
The name of the function to be called
arguments -
The values of the arguments to be supplied to the function. These will be converted if necessary to the type as defined in the function signature, using the function conversion rules.
Returns:
the result of calling the function. This is the raw result, without wrapping in a document node and without serialization.

CallFunction

public void CallFunction(QName function,
Saxon.Api.XdmValue[] arguments,
XmlDestination destination)

Call a public user-defined function in the stylesheet, wrapping the result in an XML document, and sending this document to a specified destination

Parameters:
function -
The name of the function to be called
arguments -
The values of the arguments to be supplied to the function. These will be converted if necessary to the type as defined in the function signature, using the function conversion rules.
destination -
The destination of the result document produced by wrapping the result of the apply-templates call in a document node. If the destination is a Serializer, then the serialization parameters set in the serializer are combined with those defined in the stylesheet (the parameters set in the serializer take precedence).