Package net.sf.saxon.trans

Class XsltController

  • All Implemented Interfaces:
    ContextOriginator
    public class XsltController
extends Controller
    This class is an extension of the Controller class, used when executing XSLT stylesheets.
    Since:
    9.9

    • Method Detail

      • reset

        public void reset()

        Reset this Transformer to its original configuration.

        Transformer is reset to the same state as when it was created with TransformerFactory.newTransformer(), TransformerFactory.newTransformer(javax.xml.transform.Source source) or Templates.newTransformer(). reset() is designed to allow the reuse of existing Transformers thus saving resources associated with the creation of new Transformers.

        The above is from the JAXP specification. With Saxon, it's unlikely that reusing a Transformer will give any performance benefits over creating a new one. The one case where it might be beneficial is to reuse the document pool (the set of documents that have been loaded using the doc() or document() functions). Therefore, this method does not clear the document pool. If you want to clear the document pool, call the method Controller.clearDocumentPool() as well.

        The reset Transformer is not guaranteed to have the same URIResolver or ErrorListener Objects, e.g. Object.equals(Object obj). It is guaranteed to have a functionally equal URIResolver and ErrorListener.

        Overrides:
        reset in class Controller
        Since:
        1.5

      • clearPerTransformationData

        protected void clearPerTransformationData()
        Reset variables that need to be reset for each transformation if the controller is serially reused
        Overrides:
        clearPerTransformationData in class Controller

      • setInitialMode

        public void setInitialMode​(StructuredQName expandedModeName)
                    throws XPathException
        Set the initial mode for the transformation.

        XSLT 2.0 allows a transformation to be started in a mode other than the default mode. The transformation then starts by looking for the template rule in this mode that best matches the initial context node.

        This method may eventually be superseded by a standard JAXP method.

        Parameters:
        expandedModeName - the name of the initial mode. The mode is supplied as an expanded QName. 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 unnamed mode.
        Throws:
        XPathException - if the requested mode is not defined in the stylesheet
        Since:
        8.4 Changed in 9.6 to accept a StructuredQName, and to throw an error if the mode has not been defined. Changed in 9.7 so that null indicates the default mode, which defaults to the unnamed mode but can be set otherwise in the stylesheet.

      • getInitialModeName

        public StructuredQName getInitialModeName()
        Get the name of the initial mode for the transformation
        Returns:
        the name of the initial mode; null indicates that the initial mode is the unnamed mode.

      • getInitialMode

        public Mode getInitialMode()
        Get the initial mode for the transformation
        Returns:
        the initial mode. This will be the default/unnamed mode if no specific mode has been requested

      • getAccumulatorManager

        public AccumulatorManager getAccumulatorManager()
        Get the accumulator manager for this transformation. May be null if no accumulators are in use
        Returns:
        the accumulator manager, which holds dynamic information about the values of each accumulator for each document

      • checkUniqueOutputDestination

        public boolean checkUniqueOutputDestination​(DocumentKey uri)
        Check that an output destination has not been used before, optionally adding this URI to the set of URIs that have been used.

        This method is intended for internal use only.

        Parameters:
        uri - the URI to be used as the output destination
        Returns:
        true if the URI is available for use; false if it has already been used.

      • addUnavailableOutputDestination

        public void addUnavailableOutputDestination​(DocumentKey uri)
        Add a URI to the set of output destinations that cannot be written to, either because they have already been written to, or because they have been read
        Parameters:
        uri - A URI that is not available as an output destination

      • removeUnavailableOutputDestination

        public void removeUnavailableOutputDestination​(DocumentKey uri)
        Remove a URI from the set of output destinations that cannot be written to or read from. Used to support saxon:discard-document()
        Parameters:
        uri - A URI that is being made available as an output destination

      • isUnusedOutputDestination

        public boolean isUnusedOutputDestination​(DocumentKey uri)
        Determine whether an output URI is available for use. This method is intended for use by applications, via an extension function.
        Parameters:
        uri - A uri that the application is proposing to use in the href attribute of xsl:result-document: if this function returns false, then the xsl:result-document call will fail saying the URI has already been used.
        Returns:
        true if the URI is available for use. Note that this function is not "stable": it may return different results for the same URI at different points in the transformation.

      • setInitialTemplateParameters

        public void setInitialTemplateParameters​(java.util.Map<StructuredQName,​Sequence> params,
                                         boolean tunnel)
        Set parameters for the initial template (whether this is a named template, or a template rule invoked to process the initial input item)
        Parameters:
        params - Tunnel or non-tunnel parameters to be supplied to the initial template. The supplied values will be converted to the required type using the function conversion rules. Any surplus parameters are silently ignored. May be null.
        tunnel - true if these are tunnel parameters; false if they are non-tunnel parameters
        Since:
        9.6

      • getInitialTemplateParameters

        public java.util.Map<StructuredQName,​Sequence> getInitialTemplateParameters​(boolean tunnel)
        Get the parameters for the initial template
        Parameters:
        tunnel - true if the parameters to be returned are the tunnel parameters; false for the non-tunnel parameters
        Returns:
        the parameters supplied using setInitialTemplateParameters(Map, boolean). May be null.
        Since:
        9.6

      • setMessageHandler

        public void setMessageHandler​(java.util.function.Consumer<Message> handler)
        Provide a user-supplied handler for xsl:message and xsl:assert output.

        Note that the same message handler may be called to process messages emanating from multiple threads. The message handler must therefore be thread-safe; and the order in which messages are passed to the message handler is not always predictable.

        Parameters:
        handler - a consumer of Message objects.
        Since:
        11. Replaces a variety of previous interfaces including setMessageEmitter and setMessageFactory.

      • getMessageHandler

        public java.util.function.Consumer<Message> getMessageHandler()
        Get the user-supplied or system-supplied handler for xsl:message and xsl:assert output.
        Returns:
        a consumer of Message objects.
        Since:
        11.

      • setMessageFactory

        @Deprecated
public void setMessageFactory​(java.util.function.Supplier<Receiver> messageReceiverFactory)
        Deprecated.
        since Saxon 11. The method has no effect. Use setMessageHandler(java.util.function.Consumer<net.sf.saxon.s9api.Message>)
        Supply a factory function that is called every time xsl:message is executed.
        Parameters:
        messageReceiverFactory - a factory function whose job it is to create a Outputter for xsl:message output.

      • setMessageReceiverClassName

        @Deprecated
public void setMessageReceiverClassName​(java.lang.String name)
        Deprecated.
        since Saxon 11. The method has no effect. Use setMessageHandler(java.util.function.Consumer<net.sf.saxon.s9api.Message>)
        Set the message receiver class name. This is an alternative way (retained for compatibility) of providing a factory for message receivers; it causes a message factory to be established that instantiates the supplied class
        Parameters:
        name - the full name of the class to be instantiated to provide a receiver for xsl:message output. The name must be the name of a class that implements the Receiver interface, and that has a zero-argument public constructor.

      • makeMessageReceiver

        @Deprecated
public Receiver makeMessageReceiver()
        Deprecated.
        since Saxon 11. The method returns null. Use setMessageHandler(java.util.function.Consumer<net.sf.saxon.s9api.Message>)
        Make a Receiver to be used for xsl:message output.

        This method is intended for internal use only. From 9.9.0.2 (bug 3979) this method is called to obtain a new Receiver each time an xsl:message instruction is evaluated.

        Returns:
        The newly constructed message Receiver

      • setMessageEmitter

        @Deprecated
public void setMessageEmitter​(Receiver receiver)
        Deprecated.
        since Saxon 11. The method has no effect. Use setMessageHandler(java.util.function.Consumer<net.sf.saxon.s9api.Message>)
        Set the Receiver to be used for xsl:message output.

        Recent versions of the JAXP interface specify that by default the output of xsl:message is sent to the registered ErrorListener. Saxon does not implement this convention. Instead, the output is sent to a default message emitter, which is a slightly customised implementation of the standard Saxon Emitter interface.

        This interface can be used to change the way in which Saxon outputs xsl:message output.

        It is not necessary to use this interface in order to change the destination to which messages are written: that can be achieved by obtaining the standard message emitter and calling its MessageEmitter.setWriter(java.io.Writer) method.

        Although any Receiver can be supplied as the destination for messages, applications may find it convenient to implement a subclass of SequenceWriter, in which only the abstract write() method is implemented. This will have the effect that the write() method is called to output each message as it is generated, with the Item that is passed to the write() method being the document node at the root of an XML document containing the contents of the message.

        This method is intended for use by advanced applications. The Receiver interface itself is subject to change in new Saxon releases.

        The supplied Receiver will have its open() method called once at the start of the transformation, and its close() method will be called once at the end of the transformation. Each individual call of an xsl:message instruction is wrapped by calls of startDocument() and endDocument(). If terminate="yes" is specified on the xsl:message call, the properties argument of the startDocument() call will be set to the value ReceiverOption.TERMINATE.

        Parameters:
        receiver - The receiver to receive xsl:message output.
        Since:
        8.4; changed in 8.9 to supply a Receiver rather than an Emitter. Changed in 9.9.0.2 so it is no longer supported in a configuration that allows multi-threading.

      • getMessageEmitter

        @Deprecated
public Receiver getMessageEmitter()
        Deprecated.
        since 9.9.0.2; always returns null.
        Get the Receiver used for xsl:message output. This returns the emitter previously supplied to the setMessageEmitter(net.sf.saxon.event.Receiver) method, or the default message emitter otherwise.
        Returns:
        the Receiver being used for xsl:message output
        Since:
        8.4; changed in 8.9 to return a Receiver rather than an Emitter

      • incrementMessageCounter

        public void incrementMessageCounter​(StructuredQName code)
        Increment a counter in the message counters. This method is called automatically when xsl:message is executed, to increment the counter associated with a given error code used in the xsl:message. The counters are available (in Saxon-PE and -EE) using the saxon:message-counter() extension function.
        Parameters:
        code - the error code whose counter is to be incremented

      • getMessageCounters

        public java.util.Map<StructuredQName,​java.lang.Integer> getMessageCounters()
        Get the message counters
        Returns:
        a snapshot copy of the table of message counters, indicating the number of times xsl:message has been called for each distinct error code

      • setOutputURIResolver

        public void setOutputURIResolver​(OutputURIResolver resolver)
        Set the URI resolver for secondary output documents.

        XSLT 2.0 introduces the xsl:result-document instruction, allowing a transformation to have multiple result documents. JAXP does not yet support this capability. This method allows an OutputURIResolver to be specified that takes responsibility for deciding the destination (and, if it wishes, the serialization properties) of secondary output files.

        In Saxon 9.5, because xsl:result-document is now multi-threaded, the supplied resolver is cloned each time a new result document is created. The cloned resolved is therefore able to maintain information about the specific result document for use when its close() method is called, without worrying about thread safety.

        Parameters:
        resolver - An object that implements the OutputURIResolver interface, or null.
        Since:
        8.4. Retained for backwards compatibility in 9.9, but superseded by setResultDocumentResolver(ResultDocumentResolver)

      • getResultDocumentResolver

        public ResultDocumentResolver getResultDocumentResolver()
        Get the resolver for URIs referring to secondary output documents.

        XSLT 2.0 introduced the xsl:result-document instruction, allowing a transformation to have multiple result documents. JAXP does not support this capability.

        Returns:
        An object that implements the ResultDocumentResolver interface, or null. The value is null (indicating that a system-supplied resolver will be used) unless an explicit value is set.
        Since:
        9.9.

      • setResultDocumentResolver

        public void setResultDocumentResolver​(ResultDocumentResolver resultDocumentResolver)
        Set the resolver for URIs referring to secondary output documents.

        XSLT 2.0 introduced the xsl:result-document instruction, allowing a transformation to have multiple result documents. JAXP does not support this capability. This method allows an ResultDocumentResolver to be specified that takes responsibility for deciding the destination (and, if it wishes, the serialization properties) of secondary output files.

        Parameters:
        resultDocumentResolver - An object that implements the ResultDocumentResolver interface, or null.
        Since:
        9.9.

      • setPrincipalDestination

        public void setPrincipalDestination​(Destination destination)
        Supply the Controller with information about the principal destination of the transformation
        Parameters:
        destination - the principal destination

      • getPrincipalDestination

        public Destination getPrincipalDestination()
        Get the principal destination that was supplied to the Controller
        Returns:
        the principal destination

      • setTemplateRuleTraceListener

        public void setTemplateRuleTraceListener​(TemplateRuleTraceListener templateRuleTraceListener)

      • 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

      • setAssertionsEnabled

        public void setAssertionsEnabled​(boolean enabled)
        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.
        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

      • preEvaluateGlobals

        public void preEvaluateGlobals​(XPathContext context)
                        throws XPathException
        Description copied from class: Controller
        Pre-evaluate global variables (when debugging/tracing).

        This method is intended for internal use.

        Overrides:
        preEvaluateGlobals in class Controller
        Parameters:
        context - the dynamic context for evaluating the global variables
        Throws:
        XPathException - if pre-evaluation is attempted and fails with a dynamic error

      • applyTemplates

        public void applyTemplates​(Sequence source,
                           Receiver out)
                    throws XPathException
        Perform a transformation from a Source document to a Result document.
        Parameters:
        source - The input for the source tree. May be null if and only if an initial template has been supplied.
        out - The destination for the result sequence. The events that are written to this Receiver will form a regular event sequence as defined in RegularSequenceChecker. This event sequence represents the raw results of the transformation; subsequent processing such as sequence normalization (to construct a document node) is the responsibility of the Receiver itself.
        Throws:
        XPathException - if the transformation fails. As a special case, the method throws a TerminationException (a subclass of XPathException) if the transformation was terminated using xsl:message terminate="yes".

      • getGatekeeper

        public PrincipalOutputGatekeeper getGatekeeper()
        Get the Gatekeeper object, which is used to ensure that we don't write a secondary result document to the same destination as the principal result document
        Returns:
        the gatekeeper object, or null if none is in use

      • callTemplate

        public void callTemplate​(StructuredQName initialTemplateName,
                         Receiver out)
                  throws XPathException
        Execute a transformation by evaluating a named template and delivering the "raw result".

        If any child threads are started (as a result of calls to xsl:result-document) the method will wait for these to finish before returning to the caller.

        Parameters:
        initialTemplateName - the entry point, the name of a named template
        out - The destination for the result sequence. The events that are written to this Receiver will form a regular event sequence as defined in RegularSequenceChecker. This event sequence represents the raw results of the transformation; subsequent processing such as sequence normalization (to construct a document node) is the responsibility of the Receiver itself.
        Throws:
        XPathException - if any dynamic error occurs (in this thread or in a child thread). This includes the case where the named template does not exist.

      • applyStreamingTemplates

        public void applyStreamingTemplates​(javax.xml.transform.Source source,
                                    Receiver out)
                             throws XPathException
        Perform a transformation by applying templates in a streamable mode to a streamable input document.
        Parameters:
        source - The input for the source tree.
        out - The destination for the result sequence. The events that are written to this Receiver will form a regular event sequence as defined in RegularSequenceChecker. This event sequence represents the raw results of the transformation; subsequent processing such as sequence normalization (to construct a document node) is the responsibility of the Receiver itself.
        Throws:
        XPathException - if the transformation fails. As a special case, the method throws a TerminationException (a subclass of XPathException) if the transformation was terminated using xsl:message terminate="yes".

      • getStreamingReceiver

        public Receiver getStreamingReceiver​(Mode mode,
                                     Receiver result)
                              throws XPathException
        Get a receiver to which the input to this transformation can be supplied as a stream of events, causing the transformation to be executed in streaming mode.
        Parameters:
        mode - the initial mode, which must be a streaming mode
        result - The output destination
        Returns:
        a receiver to which events can be streamed
        Throws:
        XPathException - if any dynamic error occurs

      • getAttributeSetEvaluationStack

        public java.util.Stack<AttributeSet> getAttributeSetEvaluationStack()
        Get the stack of attribute sets being evaluated (for detection of cycles)
        Returns:
        the attribute set evaluation stack

      • releaseAttributeSetEvaluationStack

        public void releaseAttributeSetEvaluationStack()