Package net.sf.saxon.s9api

## Class Xslt30Transformer

- java.lang.Object
- - net.sf.saxon.s9api.Xslt30Transformer

-     public class Xslt30Transformer
      extends java.lang.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` is 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 to reuse the object within a single thread to run several transformations using the same stylesheet, but the values of the global context item and of stylesheet parameters must be initialized before any transformations are run, and must remain unchanged thereafter.

  Some of the entry point methods are synchronized. This is not because multi-threaded execution is permitted; rather it is to reduce the damage if it is attempted.

  An `Xslt30Transformer` is always constructed by running the method `XsltExecutable.load30()`.

  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

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `baseOutputUriWasSet` |
    `protected XsltController` | `controller` |
    `protected Processor` | `processor` |

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Xslt30Transformer​(Processor processor, XsltController controller, GlobalParameterSet staticParameters)` | Protected constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `XdmValue` | `applyTemplates​(javax.xml.transform.Source source)` | Invoke the stylesheet by applying templates to a supplied Source document, returning the raw results as an `XdmValue`.
    `void` | `applyTemplates​(javax.xml.transform.Source source, Destination destination)` | Invoke the stylesheet by applying templates to a supplied Source document, sending the results (wrapped in a document node) to a given Destination.
    `XdmValue` | `applyTemplates​(XdmValue selection)` | Invoke the stylesheet by applying templates to a supplied input sequence, returning the raw results.
    `void` | `applyTemplates​(XdmValue selection, Destination destination)` | Invoke the stylesheet by applying templates to a supplied input sequence, sending the results (wrapped in a document node) to a given Destination.
    `protected void` | `applyTemplatesToSource​(javax.xml.transform.Source source, Receiver out)` |
    `Destination` | `asDocumentDestination​(Destination 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, Destination 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
    `XdmValue` | `callTemplate​(QName templateName)` | Invoke a transformation by calling a named template.
    `void` | `callTemplate​(QName templateName, Destination destination)` | Invoke a transformation by calling a named template.
    `java.lang.String` | `getBaseOutputURI()` | Get the base output URI.
    `Receiver` | `getDestinationReceiver​(XsltController controller, Destination destination)` | Get a Receiver corresponding to the chosen Destination for the transformation
    `javax.xml.transform.ErrorListener` | `getErrorListener()` | Get the ErrorListener being used during this transformation
    `ErrorReporter` | `getErrorReporter()` |
    `QName` | `getInitialMode()` | Get the name of the initial mode for the transformation, if one has been set.
    `MessageListener` | `getMessageListener()` | Get the MessageListener to be notified whenever the stylesheet evaluates an `xsl:message` instruction.
    `MessageListener2` | `getMessageListener2()` | Get the MessageListener2 to be notified whenever the stylesheet evaluates an `xsl:message` instruction.
    `protected Receiver` | `getReceivingTransformer​(XsltController controller, GlobalParameterSet parameters, Destination finalDestination)` | Return a Receiver which can be used to supply the principal source document for the transformation.
    `ValidationMode` | `getSchemaValidationMode()` | Get the schema validation mode for the transformation.
    `Logger` | `getTraceFunctionDestination()` | Get the destination for output from the fn:trace() function.
    `TraceListener` | `getTraceListener()` | Get the TraceListener to be notified of all events occurring during the transformation.
    `XsltController` | `getUnderlyingController()` | Get the underlying Controller used to implement this XsltTransformer.
    `javax.xml.transform.URIResolver` | `getURIResolver()` | Get the URI resolver.
    `boolean` | `isAssertionsEnabled()` | Ask whether assertions (xsl:assert instructions) have been enabled at run time.
    `protected boolean` | `isStreamableSource​(javax.xml.transform.Source source)` |
    `Serializer` | `newSerializer()` | Create a serializer initialised to use the default output parameters defined in the stylesheet.
    `Serializer` | `newSerializer​(java.io.File file)` | Create a serializer initialised to use the default output parameters defined in the stylesheet.
    `Serializer` | `newSerializer​(java.io.OutputStream stream)` | Create a serializer initialised to use the default output parameters defined in the stylesheet.
    `Serializer` | `newSerializer​(java.io.Writer writer)` | Create a serializer initialised to use the default output parameters defined in the stylesheet.
    `void` | `setAssertionsEnabled​(boolean enabled)` | Say whether assertions (xsl:assert instructions) should be enabled at run time.
    `void` | `setBaseOutputURI​(java.lang.String uri)` | Set the base output URI.
    `void` | `setErrorListener​(javax.xml.transform.ErrorListener listener)` | Set the ErrorListener to be used during this transformation
    `void` | `setErrorReporter​(ErrorReporter reporter)` | Set a callback that will be used when reporting a dynamic error or warning
    `void` | `setGlobalContextItem​(XdmItem globalContextItem)` | Supply the context item to be used when evaluating global variables and parameters.
    `void` | `setGlobalContextItem​(XdmItem globalContextItem, boolean alreadyStripped)` | Supply the context item to be used when evaluating global variables and parameters.
    `void` | `setInitialMode​(QName modeName)` | Set the initial mode for the transformation
    `<T extends XdmValue> void` | `setInitialTemplateParameters​(java.util.Map<QName,​T> parameters, boolean tunnel)` | Set parameters to be passed to the initial template.
    `void` | `setMessageListener​(MessageListener listener)` | Deprecated. since 10.0 - use `setMessageListener(MessageListener2)`
    `void` | `setMessageListener​(MessageListener2 listener)` | Set the MessageListener to be notified whenever the stylesheet evaluates an `xsl:message` instruction.
    `void` | `setResultDocumentHandler​(java.util.function.Function<java.net.URI,​Destination> handler)` | Set a callback function that will be used when `xsl:result-document` is evaluated.
    `void` | `setSchemaValidationMode​(ValidationMode mode)` | Set the schema validation mode for the transformation.
    `<T extends XdmValue> void` | `setStylesheetParameters​(java.util.Map<QName,​T> parameters)` | Supply the values of global stylesheet parameters.
    `void` | `setTraceFunctionDestination​(Logger stream)` | Set the destination for output from the fn:trace() function.
    `void` | `setTraceListener​(TraceListener listener)` | Set a TraceListener to be notified of all events occurring during the transformation.
    `void` | `setURIResolver​(javax.xml.transform.URIResolver resolver)` | Set an object that will be used to resolve URIs used in fn:doc() and related functions.
    `void` | `transform​(javax.xml.transform.Source source, Destination destination)` | Invoke the stylesheet by applying templates to a supplied Source document, sending the results to a given Destination.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### processor

          protected Processor processor

    - #### controller

          protected XsltController controller

    - #### baseOutputUriWasSet

          protected boolean baseOutputUriWasSet

  - ### Constructor Detail

    - #### Xslt30Transformer

          protected Xslt30Transformer​(Processor processor,
                                      XsltController controller,
                                      GlobalParameterSet staticParameters)

      Protected constructor
      Parameters:
        `processor` - the S9API processor
        `controller` - the Saxon controller object
        `staticParameters` - the static parameters supplied at stylesheet compile time

  - ### Method Detail

    - #### setGlobalContextItem

          public void setGlobalContextItem​(XdmItem globalContextItem)
                                    throws SaxonApiException

      Supply the context item to be used when evaluating global variables and parameters. A call on `setGlobalContextItem(node)` is equivalent to a call on `setGlobalContextItem(node, false)`: that is, it is assumed that stripping of type annotations and whitespace text nodes has not yet been performed.

      Note: It is more efficient to do whitespace stripping while constructing the source tree. This can be achieved by building the source tree using a `DocumentBuilder` initialized using `DocumentBuilder.setWhitespaceStrippingPolicy(WhitespaceStrippingPolicy)`, supplying a `WhitespaceStrippingPolicy` obtained by calling `XsltExecutable.getWhitespaceStrippingPolicy()`.

      Parameters:
        `globalContextItem` - 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.
      Throws:
        `java.lang.IllegalStateException` - if the transformation has already been evaluated by calling one of the methods `applyTemplates`, `callTemplate`, or `callFunction`
        `SaxonApiException` - Not thrown, but retained in the method signature for compatibility reasons. Note that no error is thrown at this stage if the context item is of the wrong type.

    - #### setGlobalContextItem

          public void setGlobalContextItem​(XdmItem globalContextItem,
                                           boolean alreadyStripped)
                                    throws SaxonApiException

      Supply the context item to be used when evaluating global variables and parameters.
      Parameters:
        `globalContextItem` - 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.
        `alreadyStripped` - true if any stripping of type annotations or whitespace text nodes specified by the stylesheet has already taken place
      Throws:
        `java.lang.IllegalStateException` - if the transformation has already been evaluated by calling one of the methods `applyTemplates`, `callTemplate`, or `callFunction`
        `SaxonApiException` - Not thrown, but retained in the method signature for compatibility reasons. Note that no error is thrown at this stage if the context item is of the wrong type.

    - #### setStylesheetParameters

          public <T extends XdmValue> void setStylesheetParameters​(java.util.Map<QName,​T> parameters)
                                                            throws SaxonApiException

      Supply the values of global stylesheet parameters.

      If a value is supplied for a parameter with a particular name, and the stylesheet does not declare a parameter with that name, then the value is simply ignored.

      If a value is supplied for a parameter with a particular name, and the stylesheet declaration of that parameter declares a required type, then the supplied value will be checked against that type when the value of the parameter is first used (and any error will be reported only then). Parameter values are converted to the required type using the function conversion rules.

      If a value is supplied for a parameter with a particular name, and the stylesheet declaration of that parameter declares it with the attribute `static="yes"`, then an error will be reported when the transformation is initiated.

      If a value is supplied for a parameter with a particular name, and a parameter with the same name was supplied at compile time using `XsltCompiler.setParameter(QName, XdmValue)`, then an error will be reported with the transformation is initiated.

      Parameters:
        `parameters` - a map whose keys are QNames identifying global stylesheet parameters, and whose corresponding values are the values to be assigned to those parameters. The contents of the supplied map are copied by this method, so subsequent changes to the map have no effect.
      Throws:
        `java.lang.IllegalStateException` - if the transformation has already been evaluated by calling one of the methods `applyTemplates`, `callTemplate`, or `callFunction`
        `SaxonApiException` - currently occurs only if the supplied value of a parameter cannot be evaluated

    - #### setInitialTemplateParameters

          public <T extends XdmValue> void setInitialTemplateParameters​(java.util.Map<QName,​T> parameters,
                                                                        boolean tunnel)
                                                                 throws SaxonApiException

      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
      Throws:
        `SaxonApiException` - not currently used, but retained in the method signature for compatibility reasons

    - #### applyTemplates

          public void applyTemplates​(javax.xml.transform.Source source,
                                     Destination destination)
                              throws SaxonApiException

      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 `setInitialMode(QName)`, and any template parameters set using `setInitialTemplateParameters(java.util.Map, boolean)`.

      This method does not set the global context item for the transformation. If that is required, it can be done separately using the method `setGlobalContextItem(XdmItem)`.

      Parameters:
        `source` - the source document. For streamed processing, this must be a SAXSource or StreamSource.

        Note: supplying a `DOMSource` is allowed, but is much less efficient than using a `StreamSource` or `SAXSource` and leaving Saxon to build the tree in its own internal format. 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).
      Throws:
        `SaxonApiException` - if the transformation fails

    - #### applyTemplates

          public XdmValue applyTemplates​(javax.xml.transform.Source source)
                                  throws SaxonApiException

      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 `setInitialMode(QName)`, and any template parameters set using `setInitialTemplateParameters(java.util.Map, boolean)`.
      Parameters:
        `source` - the source document. For streamed processing, this must be a SAXSource or StreamSource.

        Note: supplying a `DOMSource` is allowed, but is much less efficient than using a `StreamSource` or `SAXSource` and leaving Saxon to build the tree in its own internal format. To apply more than one transformation to the same source document, the source document tree can be pre-built using a `DocumentBuilder`.

      Returns:
        the raw result of processing the supplied Source using the selected template rule, without wrapping the returned sequence in a document node
      Throws:
        `SaxonApiException` - if the transformation fails

    - #### transform

          public void transform​(javax.xml.transform.Source source,
                                Destination destination)
                         throws SaxonApiException

      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 `setInitialMode(QName)` (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 `setInitialTemplateParameters(java.util.Map, boolean)`.

      The document supplied in the `source` argument also acts as the global context item for the transformation. Any item previously supplied using `setGlobalContextItem(XdmItem)` is ignored.

      Because this method sets the global context item to the root node of the supplied `source`, it cannot be used when the stylesheet is designed to process streamed input. For streamed processing, use `applyTemplates(Source, Destination)` instead.

      Parameters:
        `source` - the source document.

        Note: supplying a `DOMSource` is allowed, but is much less efficient than using a `StreamSource` or `SAXSource` and leaving Saxon to build the tree in its own internal format. 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).
      Throws:
        `SaxonApiException` - if the transformation fails, or if the initial mode in the stylesheet is declared to be streamable.
      Since:
        9.9.1.1

    - #### applyTemplates

          public void applyTemplates​(XdmValue selection,
                                     Destination destination)
                              throws SaxonApiException

      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 `setInitialMode(QName)`, and any template parameters set using `setInitialTemplateParameters(java.util.Map, 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 for the result document. In most cases this causes the raw result of the transformation to be wrapped in a document node. However, if the destination is a Serializer and the output method is "json" or "adaptive", then no wrapping takes place.
      Throws:
        `SaxonApiException` - if the transformation fails
      Since:
        9.6. Changed in 9.7.0.1 so that if a Serializer is supplied as the Destination, it will not be modified by this method to set output properties from the stylesheet; instead, the Serializer should be initialized by calling the `newSerializer` method on this `Xslt30Transformer`

    - #### applyTemplates

          public XdmValue applyTemplates​(XdmValue selection)
                                  throws SaxonApiException

      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 `setInitialMode(QName)`, and any template parameters set using `setInitialTemplateParameters(java.util.Map, 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 that one item in the selection, the result is the concatenation of the results of applying templates to each item in turn.
      Throws:
        `SaxonApiException` - if the transformation fails

    - #### callTemplate

          public void callTemplate​(QName templateName,
                                   Destination destination)
                            throws SaxonApiException

      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(java.util.Map, 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 for the result document.
      Throws:
        `SaxonApiException` - if there is no named template with this name, or if any dynamic error occurs during the transformation
      Since:
        9.6. Changed in 9.7.0.1 so that if a Serializer is supplied as the Destination, it will not be modified by this method to set output properties from the stylesheet; instead, the Serializer should be initialized by calling the `newSerializer` method on this `Xslt30Transformer`

    - #### callTemplate

          public XdmValue callTemplate​(QName templateName)
                                throws SaxonApiException

      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 node 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.
      Throws:
        `SaxonApiException` - if there is no named template with this name, or if any dynamic error occurs during the transformation

    - #### callFunction

          public XdmValue callFunction​(QName function,
                                       XdmValue[] arguments)
                                throws SaxonApiException

      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.
      Throws:
        `SaxonApiException` - if no function has been defined with the given name and arity; or if any of the arguments does not match its required type according to the function signature; or if a dynamic error occurs in evaluating the function.

    - #### callFunction

          public void callFunction​(QName function,
                                   XdmValue[] arguments,
                                   Destination destination)
                            throws SaxonApiException

      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.
      Throws:
        `SaxonApiException` - in the event of a dynamic error
      Since:
        9.6. Changed in 9.7.0.1 so that if a Serializer is supplied as the Destination, it will not be modified by this method to set output properties from the stylesheet; instead, the Serializer should be initialized by calling the `newSerializer` method on this `Xslt30Transformer`

    - #### asDocumentDestination

          public Destination asDocumentDestination​(Destination 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.

      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 `applyTemplates(Source, Destination)` method: that is, by applying templates to the root node of the supplied XML document.
      Since:
        9.9

    - #### newSerializer

          public Serializer newSerializer()

      Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of `Serializer.setOutputProperty(Serializer.Property, String)`.
      Since:
        9.7.0.1

    - #### newSerializer

          public Serializer newSerializer​(java.io.File file)

      Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of `Serializer.setOutputProperty(Serializer.Property, String)`.
      Parameters:
        `file` - the output file to which the serializer will write its output. As well as initializing the serializer to write to this output file, this method sets the base output URI of this Xslt30Transformer to be the URI of this file.
      Since:
        9.7.0.1

    - #### newSerializer

          public Serializer newSerializer​(java.io.Writer writer)

      Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of `Serializer.setOutputProperty(Serializer.Property, String)`.
      Parameters:
        `writer` - the Writer to which the serializer will write
      Since:
        9.7.0.1

    - #### newSerializer

          public Serializer newSerializer​(java.io.OutputStream stream)

      Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of `Serializer.setOutputProperty(Serializer.Property, String)`.
      Parameters:
        `stream` - the output stream to which the serializer will write
      Since:
        9.7.0.1

    - #### setBaseOutputURI

          public void setBaseOutputURI​(java.lang.String uri)

      Set the base output URI.

      This defaults to the base URI of the `Destination` for the principal output of the transformation if a destination is supplied and its base URI is known.

      If a base output URI is supplied using this method then it takes precedence over any base URI defined in the supplied `Destination` object, and it may cause the base URI of the `Destination` object to be modified in situ.

      The base output URI is used for resolving relative URIs in the `href` attribute of the `xsl:result-document` instruction; it is accessible to XSLT stylesheet code using the XPath `current-output-uri()` function

      Parameters:
        `uri` - the base output URI

    - #### getBaseOutputURI

          public java.lang.String getBaseOutputURI()

      Get the base output URI.

      This returns the value set using the `setBaseOutputURI(java.lang.String)` 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

    - #### setURIResolver

          public void setURIResolver​(javax.xml.transform.URIResolver resolver)

      Set an object that will be used to resolve URIs used in fn:doc() and related functions.
      Parameters:
        `resolver` - An object that implements the URIResolver interface, or null.

    - #### getURIResolver

          public javax.xml.transform.URIResolver getURIResolver()

      Get the URI resolver.
      Returns:
        the user-supplied URI resolver if there is one, or null otherwise

    - #### setErrorListener

          public void setErrorListener​(javax.xml.transform.ErrorListener listener)

      Set the ErrorListener to be used during this transformation
      Parameters:
        `listener` - The error listener to be used. This is notified of all dynamic errors detected during the transformation.

    - #### getErrorListener

          public javax.xml.transform.ErrorListener getErrorListener()

      Get the ErrorListener being used during this transformation
      Returns:
        listener The error listener in use. This is notified of all dynamic errors detected during the transformation. If no user-supplied ErrorListener has been set the method will return a system-supplied ErrorListener. If an explicit ErrorListener has been set using `setErrorListener(ErrorListener)`, then that ErrorListener will generally be returned, unless the internal ErrorListener has been changed by some other mechanism.

    - #### setErrorReporter

          public void setErrorReporter​(ErrorReporter reporter)

      Set a callback that will be used when reporting a dynamic error or warning

    - #### getErrorReporter

          public ErrorReporter getErrorReporter()

    - #### setResultDocumentHandler

          public void setResultDocumentHandler​(java.util.function.Function<java.net.URI,​Destination> handler)

      Set a callback function that will be used when `xsl:result-document` is evaluated. The argument is a function that takes a URI as input (specifically, the value of the `href` argument to `xsl:result-document`, resolved against the base output URI of the transformation), and returns a `Destination`, which will be used as the destination for the result document.

      If the `href` argument of the `xsl:result-document` instruction is absent or if it is set to a zero length string, then the callback function is not normally called; instead a `Receiver` for the secondary output is obtained by making a second call on `Destination.getReceiver(PipelineConfiguration, SerializationProperties)` for the principal destination of the transformation. In that situation, this result document handler is invoked only if the call on `Destination.getReceiver(PipelineConfiguration, SerializationProperties)` returns null.

      If the base output URI is absent (perhaps because the principal output destination for the transformation was supplied as a `OutputStream` or `Writer` with no associated URI or systemId), then the value of the `href` attribute is used as is if it is an absolute URI; if it is a relative URI (including the case where it is absent or zero-length) then the callback function is not called; instead a dynamic error is raised (code `SaxonErrorCode.SXRD0002`).

      If the callback function throws a `SaxonApiUncheckedException`, this will result in the `xsl:result-document` instruction failing with a dynamic error, which can be caught using `xsl:try/xsl:catch`. The error code, by default, will be "err:SXRD0001".

      The application can request to be notified when the `Destination` is closed by setting a `Destination.onClose(Action)` callback on the `Destination` object.

      Parameters:
        `handler` - the callback function to be invoked whenever an `xsl:result-document` instruction is evaluated.

    - #### setMessageListener

          public void setMessageListener​(MessageListener listener)

      Deprecated.
      since 10.0 - use `setMessageListener(MessageListener2)`
      Set the MessageListener to be notified whenever the stylesheet evaluates an `xsl:message` instruction. If no MessageListener is nominated, the output of `xsl:message` instructions will be serialized and sent to the standard error stream.
      Parameters:
        `listener` - the MessageListener to be used

    - #### setMessageListener

          public void setMessageListener​(MessageListener2 listener)

      Set the MessageListener to be notified whenever the stylesheet evaluates an `xsl:message` instruction. If no MessageListener is nominated, the output of `xsl:message` instructions will be serialized and sent to the standard error stream.

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

      Parameters:
        `listener` - the MessageListener to be used

    - #### getMessageListener

          public MessageListener getMessageListener()

      Get the MessageListener to be notified whenever the stylesheet evaluates an `xsl:message` instruction. If no MessageListener has been nominated, return null
      Returns:
        the user-supplied MessageListener, or null if none has been supplied

    - #### getMessageListener2

          public MessageListener2 getMessageListener2()

      Get the MessageListener2 to be notified whenever the stylesheet evaluates an `xsl:message` instruction. If no MessageListener2 has been nominated, return null
      Returns:
        the user-supplied MessageListener2, or null if none has been supplied

    - #### setAssertionsEnabled

          public void setAssertionsEnabled​(boolean enabled)

      Say whether assertions (xsl:assert instructions) should be 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.
      Parameters:
        `enabled` - true if assertions are to be enabled at run time; this has no effect if assertions were disabled (for a particular package) at compile time
      Since:
        9.7

    - #### isAssertionsEnabled

          public boolean isAssertionsEnabled()

      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.
      Returns:
        true if assertions are enabled at run time
      Since:
        9.7

    - #### setTraceListener

          public void setTraceListener​(TraceListener listener)

      Set a TraceListener to be notified of all events occurring during the transformation. This will only be effective if the stylesheet was compiled with trace code enabled (see `XsltCompiler.setCompileWithTracing(boolean)`)
      Parameters:
        `listener` - the TraceListener to be used. Note that the TraceListener has access to interal Saxon interfaces which may vary from one release to the next. It is also possible that the TraceListener interface itself may be changed in future releases.

    - #### getTraceListener

          public TraceListener getTraceListener()

      Get the TraceListener to be notified of all events occurring during the transformation. If no TraceListener has been nominated, return null
      Returns:
        the user-supplied TraceListener, or null if none has been supplied

    - #### setTraceFunctionDestination

          public void setTraceFunctionDestination​(Logger stream)

      Set the destination for output from the fn:trace() function. By default, the destination is System.err. If a TraceListener is in use, this is ignored, and the trace() output is sent to the TraceListener.
      Parameters:
        `stream` - the PrintStream to which trace output will be sent. If set to null, trace output is suppressed entirely. It is the caller's responsibility to close the stream after use.

    - #### getTraceFunctionDestination

          public Logger getTraceFunctionDestination()

      Get the destination for output from the fn:trace() function.
      Returns:
        the Logger to which trace output will be sent. If no explicitly destination has been set, returns System.err. If the destination has been set to null to suppress trace output, returns null.

    - #### applyTemplatesToSource

          protected void applyTemplatesToSource​(javax.xml.transform.Source source,
                                                Receiver out)
                                         throws XPathException

      Throws:
        `XPathException`

    - #### isStreamableSource

          protected boolean isStreamableSource​(javax.xml.transform.Source source)

    - #### setSchemaValidationMode

          public void setSchemaValidationMode​(ValidationMode mode)

      Set the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the `doc()`, `document()`, or `collection()` functions.
      Parameters:
        `mode` - the validation mode. Passing null causes no change to the existing value. Passing `ValidationMode.DEFAULT` resets to the initial value, which determines the validation requirements from the Saxon Configuration.

    - #### getSchemaValidationMode

          public ValidationMode getSchemaValidationMode()

      Get the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the `doc()`, `document()`, or `collection()` functions.
      Returns:
        the validation mode.

    - #### setInitialMode

          public void setInitialMode​(QName modeName)
                              throws java.lang.IllegalArgumentException

      Set the initial mode for the transformation
      Parameters:
        `modeName` - the name of the initial mode. Two special values are recognized, in the reserved XSLT namespace: xsl:unnamed to indicate the mode with no name, and xsl:default to indicate the mode defined in the stylesheet header as the default mode. The value null also indicates the default mode (which defaults to the unnamed mode, but can be set differently in an XSLT 3.0 stylesheet).
      Throws:
        `java.lang.IllegalArgumentException` - if the requested mode is not defined in the stylesheet
      Since:
        changed in 9.6 to throw an exception if the mode is not defined in the stylesheet. Chaned in 9.7 so that null means the default mode, not necessarily the unnamed mode.

    - #### getInitialMode

          public QName getInitialMode()

      Get the name of the initial mode for the transformation, if one has been set.
      Returns:
        the initial mode for the transformation. Returns null if no mode has been set, or if the mode was set to null to represent the default (unnamed) mode

    - #### getUnderlyingController

          public XsltController 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.
      Returns:
        the underlying `Controller`

    - #### getDestinationReceiver

          public Receiver getDestinationReceiver​(XsltController controller,
                                                 Destination destination)
                                          throws SaxonApiException

      Get a Receiver corresponding to the chosen Destination for the transformation
      Parameters:
        `destination` - the destination for the results of this transformation
      Returns:
        a receiver that sends the results to this destination
      Throws:
        `SaxonApiException` - if anything goes wrong

    - #### getReceivingTransformer

          protected Receiver getReceivingTransformer​(XsltController controller,
                                                     GlobalParameterSet parameters,
                                                     Destination finalDestination)
                                              throws SaxonApiException

      Return a Receiver which can be used to supply the principal source document for the transformation. This method is intended primarily for internal use, though it can also be called by a user application that wishes to feed events into the transformation engine.

      Saxon calls this method to obtain a Receiver, to which it then sends a sequence of events representing the content of an XML document. This method is provided so that `XsltTransformer` implements `Destination`, allowing one transformation to receive the results of another in a pipeline.

      Returns:
        the Receiver to which events are to be sent.
      Throws:
        `SaxonApiException` - if the Receiver cannot be created
        `java.lang.IllegalStateException` - if no Destination has been supplied