Saxon.Api

 

 

Saxon.Api

Class Xslt30Transformer

public class Xslt30Transformer

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
 bool AssertionsEnabled

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

 string BaseOutputURI

Get the base output URI.
 net.sf.saxon.trans.XsltController GetUnderlyingController

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

Supply the context item to be used when evaluating global variables and parameters. This argument can be null if no context item is to be supplied.
 QName InitialMode

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

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

 IMessageListener MessageListener

Listener for messages output using <xsl:message>.

 IMessageListener2 MessageListener2

Listener for messages output using <xsl:message>.

 IResultDocumentHandler ResultDocumentHandler

The IResultDocumentHandler to be used at run-time to process the output produced by any xsl:result-document instruction with an href attribute.

 SchemaValidationMode SchemaValidationMode

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

 bool ssAssertionsEnabled

Deprecated This property has been replaced by AssertionsEnabled.
 StandardLogger TraceFunctionDestination

Destination for output of messages using the trace() function.

 

Method Summary
 void ApplyTemplates(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 Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

 void ApplyTemplates(Stream input, Uri baseUri, XmlDestination destination)

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

 XdmValue ApplyTemplates(Stream input, Uri baseUri)

Invoke the stylesheet by applying templates to a supplied source document, using the supplied base URI, returning the raw results as an XdmValue. The invocation uses any initial mode set using Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

 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 Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

 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 Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

 XmlDestination AsDocumentDestination(XmlDestination finalDestination)

Construct a Destination object whose effect is to perform this transformation on any input that is sent to that Destination: for example, it allows this transformation to post-process the results of another transformation.

 XdmValue CallFunction(QName function, XdmValue[] arguments)

Call a public user-defined function in the stylesheet.

 void CallFunction(QName function, 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
 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 Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean) 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.

 void SetInitialTemplateParameters(Dictionary<QName, XdmValue> parameters, bool 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 SetStylesheetParameters(Dictionary<QName, XdmValue> parameters)

Supply the values of global stylesheet variables and parameters.
 void Transform(Stream input, XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied source document, sending the results to a given Destination. The invocation uses the initial mode set using Xslt30Transformer.InitialMode (defaulting to the default mode defined in the stylesheet itself, which by default is the unnamed mode). It also uses any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

 void Transform(Stream input, Uri baseUri, XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied Source document, using the supplied base URI, sending the results to a given Destination. The invocation uses the initial mode set using Xslt30Transformer.InitialMode (defaulting to the default mode defined in the stylesheet itself, which by default is the unnamed mode). It also uses any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

 

Property Detail

AssertionsEnabled

public bool AssertionsEnabled {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

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

GetUnderlyingController

public net.sf.saxon.trans.XsltController GetUnderlyingController {get; }

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

GlobalContextItem

public XdmItem GlobalContextItem {get; set; }

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

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

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.

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.

MessageListener2

public IMessageListener2 MessageListener2 {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.

The MessageListener2 property interface differs from the MessageListener in allowing the error code supplied to xsl:message to be notified

ResultDocumentHandler

public IResultDocumentHandler ResultDocumentHandler {get; set; }

The IResultDocumentHandler to be used at run-time to process the output produced by any xsl:result-document instruction with an href attribute.

In the absence of a user-supplied result document handler, the href attribute of the xsl:result-document instruction must be a valid relative URI, which is resolved against the value of the BaseOutputUri property, and the resulting absolute URI must identify a writable resource (typically a file in filestore, using the file: URI scheme).

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.

ssAssertionsEnabled

public bool ssAssertionsEnabled {get; }

Deprecated This property has been replaced by AssertionsEnabled.

Ask whether assertions (xsl:assert instructions) have been enabled at run time. This property name has been misspelt, use AssertionsEnabled instead.

TraceFunctionDestination

public StandardLogger TraceFunctionDestination {get; set; }

Destination for output of messages using the trace() function.

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.

Method Detail

ApplyTemplates

public void ApplyTemplates(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 Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

Parameters:

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 - 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 void ApplyTemplates(Stream input,
Uri baseUri,
XmlDestination destination)

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

Parameters:

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.
baseUri - Base URI used for the input document
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(Stream input,
Uri baseUri)

Invoke the stylesheet by applying templates to a supplied source document, using the supplied base URI, returning the raw results as an XdmValue. The invocation uses any initial mode set using Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

Parameters:

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.
baseUri - Base URI

Returns:

the raw result of applying templates to the supplied selection value, without wrapping in a document node or serializing the result. If there is more than one item in the selection, the result is the concatenation of the results of applying templates to each item in turn.

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 Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

Parameters:

selection - The initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates)
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 Xslt30Transformer.InitialMode, and any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

Parameters:

selection - The initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates)

Returns:

the raw result of applying templates to the supplied selection value, without wrapping in a document node or serializing the result. If there is more than one item in the selection, the result is the concatenation of the results of applying templates to each item in turn.

AsDocumentDestination

public XmlDestination AsDocumentDestination(XmlDestination finalDestination)

Construct a Destination object whose effect is to perform this transformation on any input that is sent to that Destination: for example, it allows this transformation to post-process the results of another transformation.

This method allows a pipeline of transformations to be created in which one transformation is used as the destination of another. The transformations may use streaming, in which case intermediate results will not be materialized in memory. If a transformation does not use streaming, then its input will first be assembled in memory as a node tree.

The Destination returned by this method performs sequence normalization as defined in the serialization specification: that is, the raw result of the transformation sent to this destination is wrapped into a document node. Any item-separator present in any serialization parameters is ignored (adjacent atomic values are separated by whitespace). This makes the method unsuitable for passing intermediate results other than XML document nodes.

Parameters:

finalDestination - supplied final destination

Returns:

a Destination which accepts an XML document (typically as a stream of events) and which transforms this supplied XML document (possibly using streaming) as defined by the stylesheet from which which this Xslt30Transformer was generated, sending the principal result of the transformation to the supplied finalDestination. The transformation is performed as if by the Xslt30Transformer.ApplyTemplates(Stream,XmlDestination) method: that is, by applying templates to the root node of the supplied XML document.

CallFunction

public XdmValue CallFunction(QName function,
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,
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).

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 Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean) 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 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.

Returns:

the raw results of the called template, without wrapping in a document node or serialization.

SetInitialTemplateParameters

public void SetInitialTemplateParameters(Dictionary<QName, XdmValue> parameters,
bool 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 Xslt30Transformer 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

SetStylesheetParameters

public void SetStylesheetParameters(Dictionary<QName, 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 Dictionary are copied by this method, so subsequent changes to the Dictionary have no effect.

Transform

public void Transform(Stream input,
XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied source document, sending the results to a given Destination. The invocation uses the initial mode set using Xslt30Transformer.InitialMode (defaulting to the default mode defined in the stylesheet itself, which by default is the unnamed mode). It also uses any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

since 9.9.1.5

Parameters:

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 - The destination of the principal result of the transformation. 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).

Transform

public void Transform(Stream input,
Uri baseUri,
XmlDestination destination)

Invoke the stylesheet by applying templates to a supplied Source document, using the supplied base URI, sending the results to a given Destination. The invocation uses the initial mode set using Xslt30Transformer.InitialMode (defaulting to the default mode defined in the stylesheet itself, which by default is the unnamed mode). It also uses any template parameters set using Xslt30Transformer.SetInitialTemplateParameters(Dictionary,Boolean).

since 9.9.1.5

Parameters:

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.
baseUri - Base URI used for the input document
destination - The destination of the principal result of the transformation. 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).