Package net.sf.saxon.trans

## Class XsltController

- java.lang.Object
- - net.sf.saxon.Controller
  - - net.sf.saxon.trans.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

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.Controller

      `ANONYMOUS_PRINCIPAL_OUTPUT_URI, executable, globalContextItem, inUse, principalResult, principalResultURI, traceListener, validationMode`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XsltController​(Configuration config, PreparedStylesheet pss)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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
    `void` | `applyStreamingTemplates​(javax.xml.transform.Source source, Receiver out)` | Perform a transformation by applying templates in a streamable mode to a streamable input document.
    `void` | `applyTemplates​(Sequence source, Receiver out)` | Perform a transformation from a Source document to a Result document.
    `void` | `callTemplate​(StructuredQName initialTemplateName, Receiver out)` | Execute a transformation by evaluating a named template and delivering the "raw result".
    `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.
    `protected void` | `clearPerTransformationData()` | Reset variables that need to be reset for each transformation if the controller is serially reused
    `AccumulatorManager` | `getAccumulatorManager()` | Get the accumulator manager for this transformation.
    `java.util.Stack<AttributeSet>` | `getAttributeSetEvaluationStack()` | Get the stack of attribute sets being evaluated (for detection of cycles)
    `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
    `Mode` | `getInitialMode()` | Get the initial mode for the transformation
    `StructuredQName` | `getInitialModeName()` | Get the name of the initial mode for the transformation
    `java.util.Map<StructuredQName,​Sequence>` | `getInitialTemplateParameters​(boolean tunnel)` | Get the parameters for the initial template
    `java.util.Map<StructuredQName,​java.lang.Integer>` | `getMessageCounters()` | Get the message counters
    `Receiver` | `getMessageEmitter()` | Deprecated. since 9.9.0.2; always returns null.
    `OutputURIResolver` | `getOutputURIResolver()` | Get the output URI resolver.
    `Destination` | `getPrincipalDestination()` | Get the principal destination that was supplied to the Controller
    `ResultDocumentResolver` | `getResultDocumentResolver()` |
    `Receiver` | `getStreamingReceiver​(Mode mode, Receiver result)` | 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.
    `void` | `incrementMessageCounter​(StructuredQName code)` | Increment a counter in the message counters.
    `boolean` | `isAssertionsEnabled()` | Ask whether assertions (xsl:assert instructions) have been enabled at run time.
    `boolean` | `isUnusedOutputDestination​(DocumentKey uri)` | Determine whether an output URI is available for use.
    `Receiver` | `makeMessageReceiver()` | Make a Receiver to be used for xsl:message output.
    `void` | `preEvaluateGlobals​(XPathContext context)` | Pre-evaluate global variables (when debugging/tracing).
    `void` | `releaseAttributeSetEvaluationStack()` |
    `void` | `removeUnavailableOutputDestination​(DocumentKey uri)` | Remove a URI from the set of output destinations that cannot be written to or read from.
    `void` | `reset()` | Reset this `Transformer` to its original configuration.
    `void` | `setAssertionsEnabled​(boolean enabled)` | Ask whether assertions (xsl:assert instructions) have been enabled at run time.
    `void` | `setInitialMode​(StructuredQName expandedModeName)` | Set the initial mode for the transformation.
    `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)
    `void` | `setMessageEmitter​(Receiver receiver)` | Set the Receiver to be used for xsl:message output.
    `void` | `setMessageFactory​(java.util.function.Supplier<Receiver> messageReceiverFactory)` | Supply a factory function that is called every time xsl:message is executed; the factory function is responsible for creating a `Outputter` that receives the content of the message, and does what it will with it.
    `void` | `setMessageReceiverClassName​(java.lang.String name)` | Set the message receiver class name.
    `void` | `setOutputURIResolver​(OutputURIResolver resolver)` | Set the URI resolver for secondary output documents.
    `void` | `setPrincipalDestination​(Destination destination)` | Supply the Controller with information about the principal destination of the transformation
    `void` | `setResultDocumentResolver​(ResultDocumentResolver resultDocumentResolver)` |

    - ### Methods inherited from class net.sf.saxon.Controller

      `addTraceListener, allocateSequenceOutputter, allocateSequenceOutputter, checkReadiness, clearDocumentPool, clearGlobalContextItem, getBaseOutputURI, getBindery, getCollectionFinder, getConfiguration, getConvertedParameter, getCurrentDateTime, getDefaultCollection, getDocumentPool, getErrorReporter, getExecutable, getFocusTrackerFactory, getGlobalContextItem, getImplicitTimezone, getLocalIndexes, getModel, getParameter, getPathMapForDocumentProjection, getPrincipalResult, getRememberedNumber, getRuleManager, getSchemaValidationMode, getSpaceStrippingRule, getStandardURIResolver, getStylesheetCache, getTraceFunctionDestination, getTraceListener, getUnparsedTextURIResolver, getURIResolver, getUserData, handleXPathException, initializeController, isStripSourceTree, isStylesheetContainingStripSpace, isStylesheetStrippingTypeAnnotations, isTracing, makeBuilder, makePipelineConfiguration, makeSourceTree, makeStripper, newXPathContext, pauseTracing, prepareInputTree, registerDocument, registerGlobalVariableDependency, removeTraceListener, reportFatalError, setApplyFunctionConversionRulesToExternalVariables, setBaseOutputURI, setCollectionFinder, setCurrentDateTime, setDefaultCollection, setErrorReporter, setFocusTrackerFactory, setGlobalContextItem, setGlobalContextItem, setMemoizingFocusTrackerFactory, setModel, setMultithreadedFocusTrackerFactory, setRememberedNumber, setSchemaValidationMode, setStripSourceTrees, setTraceFunctionDestination, setTraceListener, setUnparsedTextURIResolver, setURIResolver, setUseDocumentProjection, setUserData, warning`

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

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

- - ### Constructor Detail

    - #### XsltController

          public XsltController​(Configuration config,
                                PreparedStylesheet pss)

  - ### 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 `Transformer`s thus saving resources associated with the creation of new `Transformer`s.

      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` `Object`s, 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

    - #### setMessageFactory

          public void setMessageFactory​(java.util.function.Supplier<Receiver> messageReceiverFactory)

      Supply a factory function that is called every time xsl:message is executed; the factory function is responsible for creating a `Outputter` that receives the content of the message, and does what it will with it.
      Parameters:
        `messageReceiverFactory` - a factory function whose job it is to create a `Outputter` for xsl:message output; the function should supply a new `Receiver` each time it is called, because xsl:message calls may arise in different threads and the Receiver is unlikely to be thread-safe.

    - #### setMessageReceiverClassName

          public void setMessageReceiverClassName​(java.lang.String name)

      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

          public Receiver makeMessageReceiver()

      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

          public void setMessageEmitter​(Receiver receiver)

      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 `Emitter.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

          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()

    - #### setResultDocumentResolver

          public void setResultDocumentResolver​(ResultDocumentResolver resultDocumentResolver)

    - #### getOutputURIResolver

          public OutputURIResolver getOutputURIResolver()

      Get the output URI resolver.
      Returns:
        the user-supplied URI resolver if there is one, or the system-defined one otherwise.
      Since:
        8.4. Retained for backwards compatibility in 9.9; superseded by `getResultDocumentResolver()`
      See Also:
        `setOutputURIResolver(net.sf.saxon.lib.OutputURIResolver)`

    - #### 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

    - #### 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`

    - #### 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. Must be (or resolve to) a StreamSource or SAXSource.
        `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()