Package net.sf.saxon.s9api

Class Xslt30Transformer

  • public class Xslt30Transformer
extends AbstractXsltTransformer
    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. The date/time value returned by fn:current-dateTime() also remains constant for the duration of an Xslt30Transformer.

    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

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

      • getGlobalContextItem

        public XdmItem getGlobalContextItem()
        Get the global context item
        Returns:
        the global context item if it has been set, or null otherwise

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

        Type Parameters:
        T - the type of values for the parameters
        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.

        Type Parameters:
        T - the type of values for the parameters
        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 AbstractXsltTransformer.setInitialMode(QName), and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean).

        Note that this method does not cause the supplied Source document to become the global context item (that is, to be available as the value of "." when evaluating global variables. If a global context item is required, this must be set separately using setGlobalContextItem(XdmItem). Alternatively, use the transform(Source, Destination) method.

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

        Note that this method does not cause the supplied Source document to become the global context item (that is, to be available as the value of "." when evaluating global variables. If a global context item is required, this must be set separately using setGlobalContextItem(XdmItem). Alternatively, use the transform(Source, Destination) method.

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

        Note that this method does not cause the supplied Source document to become the global context item (that is, to be available as the value of "." when evaluating global variables. If a global context item is required, this must be set separately using setGlobalContextItem(XdmItem). Alternatively, use the transform(Source, Destination) method.

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

        Note that this method does not cause the supplied selection to become the global context item (that is, to be available as the value of "." when evaluating global variables. If a global context item is required, this must be set separately using setGlobalContextItem(XdmItem). Alternatively, use the transform(Source, Destination) method.

        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.

        Parameters:
        finalDestination - the destination for the principal result of this transformation
        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.
        Returns:
        the new serializer
        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
        Returns:
        the new serializer
        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
        Returns:
        the new serializer
        Since:
        9.7.0.1