Package net.sf.saxon.s9api

Class 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 Detail

      • 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​(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

      • 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.

      • 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