Package net.sf.saxon

## Class Controller

- java.lang.Object
- - net.sf.saxon.Controller

- All Implemented Interfaces:
    `ContextOriginator`
  Direct Known Subclasses:
    `XsltController`

      public class Controller
      extends java.lang.Object
      implements ContextOriginator

  The Controller underpins Saxon's implementation of the JAXP Transformer class, and represents an executing instance of a transformation or query. Multiple concurrent executions of the same transformation or query will use different Controller instances. This class is therefore not thread-safe.

  The Controller is serially reusable: when one transformation or query is finished, it can be used to run another. However, there is no advantage in doing this rather than allocating a new Controller each time.

  A dummy Controller is created when running free-standing XPath expressions.

  The Controller holds those parts of the dynamic context that do not vary during the course of a transformation or query, or that do not change once their value has been computed. This also includes those parts of the static context that are required at run-time.

  Many methods on the Controller are designed for internal use and should not be considered stable. From release 8.4 onwards, those methods that are considered sufficiently stable to constitute path of the Saxon public API are labelled with the JavaDoc tag "since": the value indicates the release at which the method was added to the public API.

  Prior to Saxon 9.6 the Controller implemented (extended) the JAXP `Transformer` interface, and advanced applications were able to down-cast the Transformer to a Controller. This is no longer the case. Instead, the JAXP factory delivers an instance of `TransformerImpl`, from which the Controller is accessible if required. Because the Controller is no longer required to implement the JAXP interface, it has been possible to make it less monolithic, so some of the things it did are now done elsewhere: for example, it no longer handles global parameters

  Since:
    8.4. From 9.6 this class should no longer be considered a public API. In 9.9, the class was split into two: XSLT-specific functionality has been moved into the subclass `XsltController`.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ANONYMOUS_PRINCIPAL_OUTPUT_URI` |
    `protected Executable` | `executable` |
    `protected Item` | `globalContextItem` |
    `protected boolean` | `inUse` |
    `protected Receiver` | `principalResult` |
    `protected java.lang.String` | `principalResultURI` |
    `protected TraceListener` | `traceListener` |
    `protected int` | `validationMode` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Controller​(Configuration config)` | Create a Controller and initialise variables.
    `Controller​(Configuration config, Executable executable)` | Create a Controller and initialise variables.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addTraceListener​(TraceListener trace)` | Adds the specified trace listener to receive trace events from this instance.
    `SequenceCollector` | `allocateSequenceOutputter()` | Allocate a SequenceOutputter for a new output destination.
    `SequenceCollector` | `allocateSequenceOutputter​(int size)` | Allocate a SequenceCollector for a new output destination.
    `protected void` | `checkReadiness()` |
    `void` | `clearDocumentPool()` | Clear the document pool.
    `void` | `clearGlobalContextItem()` | Reset the global context item to null.
    `protected void` | `clearPerTransformationData()` | Reset variables that need to be reset for each transformation if the controller is serially reused
    `java.lang.String` | `getBaseOutputURI()` | Get the base output URI.
    `Bindery` | `getBindery​(PackageData packageData)` | Get the bindery for the global variables in a particular package.
    `CollectionFinder` | `getCollectionFinder()` | Get the collection finder associated with this configuration.
    `Configuration` | `getConfiguration()` | Get the Configuration associated with this Controller.
    `GroundedValue` | `getConvertedParameter​(StructuredQName name, SequenceType requiredType, XPathContext context)` | Get the value of a parameter, converted and/or type-checked
    `DateTimeValue` | `getCurrentDateTime()` | Get the current date and time for this query or transformation.
    `java.lang.String` | `getDefaultCollection()` | Get the name of the default collection.
    `DocumentPool` | `getDocumentPool()` | Get the document pool.
    `ErrorReporter` | `getErrorReporter()` |
    `Executable` | `getExecutable()` | Get the Executable object.
    `java.util.function.Function<SequenceIterator,​FocusTrackingIterator>` | `getFocusTrackerFactory​(boolean multithreaded)` | Get the factory function that is used to create new instances of FocusTrackingIterator.
    `Item` | `getGlobalContextItem()` | Get the item used as the context for evaluating global variables.
    `int` | `getImplicitTimezone()` | Get the implicit timezone offset for this query or transformation
    `IntHashMap<java.util.Map<java.lang.Long,​KeyIndex>>` | `getLocalIndexes()` | Get the table of local indexes supporting xsl:key (or implicit keys created by the optimizer).
    `TreeModel` | `getModel()` | Get the tree model that will be used.
    `Sequence` | `getParameter​(StructuredQName name)` | Get the value of a supplied parameter (XSLT) or external variable (XQuery)
    `PathMap` | `getPathMapForDocumentProjection()` | Get the path map used for document projection, if any.
    `Receiver` | `getPrincipalResult()` | Get the principal result destination.
    `int` | `getRememberedNumber​(NodeInfo node)` | Get the number of a node if it is the last remembered one.
    `RuleManager` | `getRuleManager()` | Get the Rule Manager.
    `int` | `getSchemaValidationMode()` | Ask whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method should be subjected to schema validation
    `SpaceStrippingRule` | `getSpaceStrippingRule()` | Return the default whitespace-stripping rules that apply to this transformation or query.
    `javax.xml.transform.URIResolver` | `getStandardURIResolver()` | Get the fallback URI resolver.
    `StylesheetCache` | `getStylesheetCache()` | Get the cache of stylesheets (cached during calls on fn:transform()) for this query or transformation.
    `Logger` | `getTraceFunctionDestination()` | Get the destination for output from the fn:trace() function.
    `TraceListener` | `getTraceListener()` | Get the TraceListener.
    `UnparsedTextURIResolver` | `getUnparsedTextURIResolver()` | Get the URI resolver for the unparsed-text() function.
    `javax.xml.transform.URIResolver` | `getURIResolver()` | Get the URI resolver.
    `java.lang.Object` | `getUserData​(java.lang.Object key, java.lang.String name)` | Get user data associated with a key.
    `protected void` | `handleXPathException​(XPathException err)` |
    `void` | `initializeController​(GlobalParameterSet params)` | Initialize the controller ready for a new transformation.
    `boolean` | `isStripSourceTree()` | Ask whether the transformation will perform whitespace stripping for supplied source trees as defined by the xsl:strip-space and xsl:preserve-space declarations in the stylesheet.
    `protected boolean` | `isStylesheetContainingStripSpace()` | Ask whether the executable is a stylesheet whose top-level package contains an xsl:strip-space declaration requesting stripping of whitespace from the principal source document to the transformation
    `boolean` | `isStylesheetStrippingTypeAnnotations()` | Ask whether the executable is a stylesheet whose top-level package contains requests stripping of type annotations
    `boolean` | `isTracing()` | Test whether instruction execution is being traced.
    `Builder` | `makeBuilder()` | Make a builder for the selected tree model.
    `PipelineConfiguration` | `makePipelineConfiguration()` | Make a PipelineConfiguration based on the properties of this Controller.
    `NodeInfo` | `makeSourceTree​(javax.xml.transform.Source source, int validationMode)` | Make a source tree from a source supplied as a StreamSource or SAXSource
    `Stripper` | `makeStripper​(Receiver next)` | Make a Stripper configured to implement the whitespace stripping rules.
    `XPathContextMajor` | `newXPathContext()` | Make an XPathContext object for expression evaluation.
    `void` | `pauseTracing​(boolean pause)` | Pause or resume tracing.
    `void` | `preEvaluateGlobals​(XPathContext context)` | Pre-evaluate global variables (when debugging/tracing).
    `NodeInfo` | `prepareInputTree​(javax.xml.transform.Source source)` | Prepare an input tree for processing.
    `void` | `registerDocument​(TreeInfo doc, DocumentKey uri)` | Add a document to the document pool, and check that it is suitable for use in this query or transformation.
    `void` | `registerGlobalVariableDependency​(GlobalVariable one, GlobalVariable two)` | Register the dependency of one variable ("one") upon another ("two"), throwing an exception if this would establish a cycle of dependencies.
    `void` | `removeTraceListener​(TraceListener trace)` | Removes the specified trace listener so that the listener will no longer receive trace events.
    `void` | `reportFatalError​(XPathException err)` | Report a fatal error
    `void` | `reset()` | Reset this `Transformer` to its original configuration.
    `void` | `setApplyFunctionConversionRulesToExternalVariables​(boolean applyConversionRules)` |
    `void` | `setBaseOutputURI​(java.lang.String uri)` | Set the base output URI.
    `void` | `setCollectionFinder​(CollectionFinder cf)` | Set the collection finder associated with this configuration.
    `void` | `setCurrentDateTime​(DateTimeValue dateTime)` | Set the current date and time for this query or transformation.
    `void` | `setDefaultCollection​(java.lang.String uri)` | Set the name of the default collection.
    `void` | `setErrorReporter​(ErrorReporter reporter)` | Set a callback that will be used when reporting a dynamic error or warning
    `void` | `setFocusTrackerFactory​(java.util.function.Function<SequenceIterator,​FocusTrackingIterator> focusTrackerFactory)` | Set a factory function that will be used to create new instances of FocusTrackingIterator.
    `void` | `setGlobalContextItem​(Item contextItem)` | Set the item used as the context for evaluating global variables.
    `void` | `setGlobalContextItem​(Item contextItem, boolean alreadyStripped)` | Set the item used as the context for evaluating global variables.
    `void` | `setMemoizingFocusTrackerFactory()` | Set the focus tracker factory function to a function that creates a memoizing focus tracker, which has the effect that all items read by the focus iterator are accessible to a debugger at any stage while iterating over the sequence
    `void` | `setModel​(TreeModel model)` | Set the tree model to use.
    `void` | `setMultithreadedFocusTrackerFactory​(java.util.function.Function<SequenceIterator,​FocusTrackingIterator> focusTrackerFactory)` | Set a factory function that will be used to create new instances of FocusTrackingIterator for multithreaded operation.
    `void` | `setRememberedNumber​(NodeInfo node, int number)` | Set the last remembered node, for node numbering purposes.
    `void` | `setSchemaValidationMode​(int validationMode)` | Say whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method, should be subjected to schema validation.
    `void` | `setStripSourceTrees​(boolean strip)` | Say whether the transformation should perform whitespace stripping as defined by the xsl:strip-space and xsl:preserve-space declarations in the stylesheet in the case where a source tree is supplied to the transformation as a tree (typically a DOMSource, or a Saxon NodeInfo).
    `void` | `setTraceFunctionDestination​(Logger stream)` | Set the destination for output from the fn:trace() function.
    `void` | `setTraceListener​(TraceListener listener)` | Set a TraceListener, replacing any existing TraceListener
    `void` | `setUnparsedTextURIResolver​(UnparsedTextURIResolver resolver)` | Set an UnparsedTextURIResolver to be used to resolve URIs passed to the XSLT unparsed-text() function.
    `void` | `setURIResolver​(javax.xml.transform.URIResolver resolver)` | Set an object that will be used to resolve URIs used in document(), etc.
    `void` | `setUseDocumentProjection​(PathMap pathMap)` | Indicate whether document projection should be used, and supply the PathMap used to control it.
    `void` | `setUserData​(java.lang.Object key, java.lang.String name, java.lang.Object data)` | Set user data associated with a key.
    `void` | `warning​(java.lang.String message, java.lang.String errorCode, Location locator)` | Report a run-time warning

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

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

- - ### Field Detail

    - #### executable

          protected Executable executable

    - #### globalContextItem

          protected Item globalContextItem

    - #### traceListener

          protected TraceListener traceListener

    - #### principalResult

          protected Receiver principalResult

    - #### principalResultURI

          protected java.lang.String principalResultURI

    - #### validationMode

          protected int validationMode

    - #### inUse

          protected boolean inUse

    - #### ANONYMOUS_PRINCIPAL_OUTPUT_URI

          public static final java.lang.String ANONYMOUS_PRINCIPAL_OUTPUT_URI

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Controller

          public Controller​(Configuration config)

      Create a Controller and initialise variables. Note: XSLT applications should create the Controller by using the JAXP newTransformer() method, or in S9API by using XsltExecutable.load()
      Parameters:
        `config` - The Configuration used by this Controller

    - #### Controller

          public Controller​(Configuration config,
                            Executable executable)

      Create a Controller and initialise variables.
      Parameters:
        `config` - The Configuration used by this Controller
        `executable` - The executable used by this Controller

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

      Since:
        1.5

    - #### clearPerTransformationData

          protected void clearPerTransformationData()

      Reset variables that need to be reset for each transformation if the controller is serially reused

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Configuration associated with this Controller. The Configuration holds settings that potentially apply globally to many different queries and transformations.
      Returns:
        the Configuration object
      Since:
        8.4

    - #### getParameter

          public Sequence getParameter​(StructuredQName name)

      Get the value of a supplied parameter (XSLT) or external variable (XQuery)
      Parameters:
        `name` - the QName of the parameter
      Returns:
        the supplied value of the parameter, if such a parameter exists, and if a value was supplied. Returns null if the parameter is not declared or if no value was supplied, even if there is a default defined in the stylesheet or query.

    - #### getConvertedParameter

          public GroundedValue getConvertedParameter​(StructuredQName name,
                                                     SequenceType requiredType,
                                                     XPathContext context)
                                              throws XPathException

      Get the value of a parameter, converted and/or type-checked
      Parameters:
        `name` - the name of the stylesheet parameter (XSLT) or external variable (XQuery)
        `requiredType` - the declared type of the parameter
        `context` - the dynamic evaluation context
      Returns:
        the parameter value if defined, or null otherwise. If the option `setApplyFunctionConversionRulesToExternalVariables(boolean)`} is set, the supplied value is converted to the required type. Otherwise, the supplied value is checked against the required type.
      Throws:
        `XPathException` - if a problem is found with the supplied parameter value

    - #### setBaseOutputURI

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

      Set the base output URI.

      This defaults to the system ID of the Result object for the principal output of the transformation if this is known; if it is not known, it defaults to the current directory.

      The base output URI is used for resolving relative URIs in the `href` attribute of the `xsl:result-document` instruction.

      Parameters:
        `uri` - the base output URI
      Since:
        8.4

    - #### 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
      Since:
        8.4

    - #### getPrincipalResult

          public Receiver getPrincipalResult()

      Get the principal result destination.

      This method is intended for internal use only. It is typically called by Saxon during the course of a transformation, to discover the result that was supplied in the transform() call.

      Returns:
        the Result object supplied as the principal result destination.

    - #### allocateSequenceOutputter

          public SequenceCollector allocateSequenceOutputter()

      Allocate a SequenceOutputter for a new output destination.
      Returns:
        the allocated SequenceOutputter

    - #### allocateSequenceOutputter

          public SequenceCollector allocateSequenceOutputter​(int size)

      Allocate a SequenceCollector for a new output destination.
      Parameters:
        `size` - the estimated size of the output sequence
      Returns:
        SequenceOutputter the allocated SequenceOutputter

    - #### makePipelineConfiguration

          public PipelineConfiguration makePipelineConfiguration()

      Make a PipelineConfiguration based on the properties of this Controller.

      This interface is intended primarily for internal use, although it may be necessary for applications to call it directly if they construct pull or push pipelines.

      Returns:
        a newly constructed PipelineConfiguration holding a reference to this Controller as well as other configuration information.

    - #### setErrorReporter

          public void setErrorReporter​(ErrorReporter reporter)

      Set a callback that will be used when reporting a dynamic error or warning
      Parameters:
        `reporter` - the error reporter to be notified

    - #### getErrorReporter

          public ErrorReporter getErrorReporter()

    - #### reportFatalError

          public void reportFatalError​(XPathException err)

      Report a fatal error
      Parameters:
        `err` - the error to be reported

    - #### warning

          public void warning​(java.lang.String message,
                              java.lang.String errorCode,
                              Location locator)

      Report a run-time warning
      Parameters:
        `message` - the warning message
        `errorCode` - the local part of the error code (in the ERR namespace). May be null.
        `locator` - the location in the source code. May be null.

    - #### handleXPathException

          protected void handleXPathException​(XPathException err)
                                       throws XPathException

      Throws:
        `XPathException`

    - #### getExecutable

          public Executable getExecutable()

      Get the Executable object.

      This method is intended for internal use only.

      Returns:
        the Executable (which represents the compiled stylesheet)

    - #### getDocumentPool

          public DocumentPool getDocumentPool()

      Get the document pool. This is used only for source documents, not for stylesheet modules.

      This method is intended for internal use only.

      Returns:
        the source document pool

    - #### clearDocumentPool

          public void clearDocumentPool()

      Clear the document pool. This is sometimes useful when re-using the same Transformer for a sequence of transformations, but it isn't done automatically, because when the transformations use common look-up documents, the caching is beneficial.

    - #### getBindery

          public Bindery getBindery​(PackageData packageData)

      Get the bindery for the global variables in a particular package.

      This method is intended for internal use only.

      Parameters:
        `packageData` - the package for which the variables are required
      Returns:
        the Bindery (in which values of all variables for the requested package are held)

    - #### setGlobalContextItem

          public void setGlobalContextItem​(Item contextItem)
                                    throws XPathException

      Set the item used as the context for evaluating global variables. This value is used as the global context item by XQuery, XSLT and XPath.
      Parameters:
        `contextItem` - the context item for evaluating global variables, or null if there is none
      Throws:
        `XPathException` - if the supplied context item is a node, and if it (a) does not belong to the right Configuration, or (b) is schema-validated, when the stylesheet or query is not compiled with schema-awareness enabled
      Since:
        9.7. Changed in 9.9 to raise an exception if the context item is inappropriate.

    - #### setGlobalContextItem

          public void setGlobalContextItem​(Item contextItem,
                                           boolean alreadyStripped)
                                    throws XPathException

      Set the item used as the context for evaluating global variables. This value is used as the global context item by XQuery, XSLT, and XPath.
      Parameters:
        `contextItem` - the context item for evaluating global variables, or null if there is none
        `alreadyStripped` - true if any stripping of type annotations or whitespace text node specified in the stylesheet has already been carried out
      Throws:
        `XPathException` - if the supplied context item is a node, and if it (a) does not belong to the right Configuration, or (b) is schema-validated, when the stylesheet or query is not compiled with schema-awareness enabled
      Since:
        9.7. Changed in 9.9 to raise an exception if the context item is inappropriate.

    - #### clearGlobalContextItem

          public void clearGlobalContextItem()

      Reset the global context item to null. This clears any previous setting of the global context item.

    - #### getGlobalContextItem

          public Item getGlobalContextItem()

      Get the item used as the context for evaluating global variables. In XQuery this is the same as the initial context item; in XSLT 1.0 and 2.0 it is the root of the tree containing the initial context node; in XSLT 3.0 it can be set independently of the initial match selection.
      Returns:
        the context item for evaluating global variables, or null if there is none
      Since:
        9.7

    - #### setURIResolver

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

      Set an object that will be used to resolve URIs used in document(), etc.
      Parameters:
        `resolver` - An object that implements the URIResolver interface, or null.

    - #### getURIResolver

          public javax.xml.transform.URIResolver getURIResolver()

      Get the URI resolver.

      This method changed in Saxon 8.5, to conform to the JAXP specification. If there is no user-specified URIResolver, it now returns null; previously it returned the system default URIResolver.

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

    - #### getStandardURIResolver

          public javax.xml.transform.URIResolver getStandardURIResolver()

      Get the fallback URI resolver. This is the URIResolver that Saxon uses when the user-supplied URI resolver returns null.

      This method is intended for internal use only.

      Returns:
        the the system-defined URIResolver

    - #### setUnparsedTextURIResolver

          public void setUnparsedTextURIResolver​(UnparsedTextURIResolver resolver)

      Set an UnparsedTextURIResolver to be used to resolve URIs passed to the XSLT unparsed-text() function.
      Parameters:
        `resolver` - the unparsed text URI resolver to be used. This replaces any unparsed text URI resolver previously registered.
      Since:
        8.9

    - #### getUnparsedTextURIResolver

          public UnparsedTextURIResolver getUnparsedTextURIResolver()

      Get the URI resolver for the unparsed-text() function. This will return the UnparsedTextURIResolver previously set using the `setUnparsedTextURIResolver(net.sf.saxon.lib.UnparsedTextURIResolver)` method.
      Returns:
        the registered UnparsedTextURIResolver
      Since:
        8.9

    - #### getCollectionFinder

          public CollectionFinder getCollectionFinder()

      Get the collection finder associated with this configuration. This is used to dereference collection URIs used in the fn:collection and fn:uri-collection functions
      Returns:
        the CollectionFinder to be used
      Since:
        9.7

    - #### setCollectionFinder

          public void setCollectionFinder​(CollectionFinder cf)

      Set the collection finder associated with this configuration. This is used to dereference collection URIs used in the fn:collection and fn:uri-collection functions
      Parameters:
        `cf` - the CollectionFinder to be used
      Since:
        9.7

    - #### setDefaultCollection

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

      Set the name of the default collection. Defaults to the default collection name registered with the Configuration.
      Parameters:
        `uri` - the collection URI of the default collection. May be null, to cause fallback to the collection name registered with the Configuration. The name will be passed to the collection URI resolver to identify the documents in the collection, unless the name is `http://saxon.sf.net/collection/empty` which always refers to the empty collection.
      Since:
        9.4

    - #### getDefaultCollection

          public java.lang.String getDefaultCollection()

      Get the name of the default collection. Defaults to the default collection name registered with the Configuration.
      Returns:
        the collection URI of the default collection. If no value has been set explicitly, the collection URI registered with the Configuration is returned
      Since:
        9.4

    - #### getSchemaValidationMode

          public int getSchemaValidationMode()

      Ask whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method should be subjected to schema validation
      Returns:
        the schema validation mode previously set using setSchemaValidationMode(), or the default mode (derived from the global Configuration) otherwise.

    - #### setSchemaValidationMode

          public void setSchemaValidationMode​(int validationMode)

      Say whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method, should be subjected to schema validation. The default value is taken from the corresponding property of the Configuration.
      Parameters:
        `validationMode` - the validation (or construction) mode to be used for source documents. One of `Validation.STRIP`, `Validation.PRESERVE`, `Validation.STRICT`, `Validation.LAX`
      Since:
        9.2

    - #### setModel

          public void setModel​(TreeModel model)

      Set the tree model to use. Default is the tiny tree
      Parameters:
        `model` - typically one of the constants `TreeModel.TINY_TREE`, `TreeModel.TINY_TREE_CONDENSED`, or `TreeModel.LINKED_TREE`. It is also possible to use a user-defined tree model.
      Since:
        9.2

    - #### getModel

          public TreeModel getModel()

      Get the tree model that will be used.
      Returns:
        typically one of the constants `TreeModel.TINY_TREE`, `TreeModel.TINY_TREE_CONDENSED`, or `TreeModel.LINKED_TREE`. It is also possible to use a user-defined tree model.
      Since:
        9.2

    - #### makeBuilder

          public Builder makeBuilder()

      Make a builder for the selected tree model.
      Returns:
        an instance of the Builder for the chosen tree model
      Since:
        8.4

    - #### setStripSourceTrees

          public void setStripSourceTrees​(boolean strip)

      Say whether the transformation should perform whitespace stripping as defined by the xsl:strip-space and xsl:preserve-space declarations in the stylesheet in the case where a source tree is supplied to the transformation as a tree (typically a DOMSource, or a Saxon NodeInfo). The default is true. It is legitimate to suppress whitespace stripping if the client knows that all unnecessary whitespace has already been removed from the tree before it is processed. Note that this option applies to all source documents for which whitespace-stripping is normally applied, that is, both the principal source documents, and documents read using the doc(), document(), and collection() functions. It does not apply to source documents that are supplied in the form of a SAXSource or StreamSource, for which whitespace is stripped during the process of tree construction.

      Generally, stripping whitespace speeds up the transformation if it is done while building the source tree, but slows it down if it is applied to a tree that has already been built. So if the same source tree is used as input to a number of transformations, it is better to strip the whitespace once at the time of tree construction, rather than doing it on-the-fly during each transformation.

      Parameters:
        `strip` - true if whitespace is to be stripped from supplied source trees as defined by xsl:strip-space; false to suppress whitespace stripping
      Since:
        9.3

    - #### isStripSourceTree

          public boolean isStripSourceTree()

      Ask whether the transformation will perform whitespace stripping for supplied source trees as defined by the xsl:strip-space and xsl:preserve-space declarations in the stylesheet.
      Returns:
        true unless whitespace stripping has been suppressed using `setStripSourceTrees(boolean)`.
      Since:
        9.3

    - #### isStylesheetContainingStripSpace

          protected boolean isStylesheetContainingStripSpace()

      Ask whether the executable is a stylesheet whose top-level package contains an xsl:strip-space declaration requesting stripping of whitespace from the principal source document to the transformation
      Returns:
        true if whitespace stripping has been requested

    - #### isStylesheetStrippingTypeAnnotations

          public boolean isStylesheetStrippingTypeAnnotations()

      Ask whether the executable is a stylesheet whose top-level package contains requests stripping of type annotations
      Returns:
        true if stripping of type annotations has been requested

    - #### makeStripper

          public Stripper makeStripper​(Receiver next)

      Make a Stripper configured to implement the whitespace stripping rules. In the case of XSLT the whitespace stripping rules are normally defined by `xsl:strip-space` and `xsl:preserve-space` elements in the stylesheet. Alternatively, stripping of all whitespace text nodes may be defined at the level of the Configuration, using the code `Configuration.getParseOptions().setSpaceStrippingRules(AllElementsSpaceStrippingRule.getInstance()`.
      Parameters:
        `next` - the Receiver to which the events filtered by this stripper are to be sent (often a Builder). May be null if the stripper is not being used for filtering into a Builder or other Receiver.
      Returns:
        the required Stripper. A Stripper may be used in two ways. It acts as a filter applied to an event stream, that can be used to remove the events representing whitespace text nodes before they reach a Builder. Alternatively, it can be used to define a view of an existing tree in which the whitespace text nodes are dynamically skipped while navigating the XPath axes.
      Since:
        8.4 - Generalized in 8.5 to accept any Receiver as an argument

    - #### getSpaceStrippingRule

          public SpaceStrippingRule getSpaceStrippingRule()

      Return the default whitespace-stripping rules that apply to this transformation or query.
      Returns:
        If the configuration-level whitespace-stripping rule is to strip whitespace for all elements, then AllElementsSpaceStrippingRule.getInstance(). Otherwise,

    - #### registerDocument

          public void registerDocument​(TreeInfo doc,
                                       DocumentKey uri)
                                throws XPathException

      Add a document to the document pool, and check that it is suitable for use in this query or transformation. This check rejects the document if document has been validated (and thus carries type annotations) but the query or transformation is not schema-aware.

      This method is intended for internal use only.

      Parameters:
        `doc` - the root node of the document to be added. Must not be null.
        `uri` - the document-URI property of this document. If non-null, the document is registered in the document pool with this as its document URI.
      Throws:
        `XPathException` - if an error occurs

    - #### getRuleManager

          public RuleManager getRuleManager()

      Get the Rule Manager.

      This method is intended for internal use only.

      Returns:
        the Rule Manager, used to hold details of template rules for all modes; or null in the case of a non-XSLT controller

    - #### setTraceListener

          public void setTraceListener​(TraceListener listener)

      Set a TraceListener, replacing any existing TraceListener

      This method has no effect unless the stylesheet or query was compiled with tracing enabled.

      Parameters:
        `listener` - the TraceListener to be set. May be null, in which case trace events will not be reported
      Since:
        9.2

    - #### getTraceListener

          public TraceListener getTraceListener()

      Get the TraceListener. By default, there is no TraceListener, and this method returns null. A TraceListener may be added using the method `addTraceListener(net.sf.saxon.lib.TraceListener)`. If more than one TraceListener has been added, this method will return a composite TraceListener. Because the form this takes is implementation-dependent, this method is not part of the stable Saxon public API.
      Returns:
        the TraceListener used for XSLT or XQuery instruction tracing, or null if absent.

    - #### isTracing

          public final boolean isTracing()

      Test whether instruction execution is being traced. This will be true if (a) at least one TraceListener has been registered using the `addTraceListener(net.sf.saxon.lib.TraceListener)` method, and (b) tracing has not been temporarily paused using the `pauseTracing(boolean)` method.
      Returns:
        true if tracing is active, false otherwise
      Since:
        8.4

    - #### pauseTracing

          public final void pauseTracing​(boolean pause)

      Pause or resume tracing. While tracing is paused, trace events are not sent to any of the registered TraceListeners.
      Parameters:
        `pause` - true if tracing is to pause; false if it is to resume
      Since:
        8.4

    - #### addTraceListener

          public void addTraceListener​(TraceListener trace)

      Adds the specified trace listener to receive trace events from this instance. Note that although TraceListeners can be added or removed dynamically, this has no effect unless the stylesheet or query has been compiled with tracing enabled. This is achieved by calling `Configuration.setTraceListener(net.sf.saxon.lib.TraceListener)` or by setting the attribute `FeatureKeys.TRACE_LISTENER` on the TransformerFactory. Conversely, if this property has been set in the Configuration or TransformerFactory, the TraceListener will automatically be added to every Controller that uses that Configuration.
      Parameters:
        `trace` - the trace listener. If null is supplied, the call has no effect.
      Since:
        8.4

    - #### removeTraceListener

          public void removeTraceListener​(TraceListener trace)

      Removes the specified trace listener so that the listener will no longer receive trace events.
      Parameters:
        `trace` - the trace listener.
      Since:
        8.4

    - #### 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.
      Since:
        9.1. Changed in 9.6 to use a Logger

    - #### getTraceFunctionDestination

          public Logger getTraceFunctionDestination()

      Get the destination for output from the fn:trace() function.
      Returns:
        the PrintStream 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.
      Since:
        9.1. Changed in 9.6 to use a Logger

    - #### initializeController

          public void initializeController​(GlobalParameterSet params)
                                    throws XPathException

      Initialize the controller ready for a new transformation. This method should not normally be called by users (it is done automatically when transform() is invoked). However, it is available as a low-level API especially for use with XQuery.
      Parameters:
        `params` - the values of stylesheet parameters. Changed in 9.9.1.1 so this no longer includes static parameters (which are already available in the `PreparedStylesheet`).
      Throws:
        `XPathException` - if an error occurs, for example if a required parameter is not supplied.

    - #### setApplyFunctionConversionRulesToExternalVariables

          public void setApplyFunctionConversionRulesToExternalVariables​(boolean applyConversionRules)

    - #### getUserData

          public java.lang.Object getUserData​(java.lang.Object key,
                                              java.lang.String name)

      Get user data associated with a key. To retrieve user data, two objects are required: an arbitrary object that may be regarded as the container of the data (originally, and typically still, a node in a tree), and a name. The name serves to distingush data objects associated with the same node by different client applications.

      This method is intended primarily for internal use, though it may also be used by advanced applications.

      Parameters:
        `key` - an object acting as a key for this user data value. This must be equal (in the sense of the equals() method) to the key supplied when the data value was registered using `setUserData(java.lang.Object, java.lang.String, java.lang.Object)`.
        `name` - the name of the required property
      Returns:
        the value of the required property

    - #### setUserData

          public void setUserData​(java.lang.Object key,
                                  java.lang.String name,
                                  java.lang.Object data)

      Set user data associated with a key. To store user data, two objects are required: an arbitrary object that may be regarded as the container of the data (originally, and typically still, a node in a tree), and a name. The name serves to distingush data objects associated with the same node by different client applications.

      This method is intended primarily for internal use, though it may also be used by advanced applications.

      Parameters:
        `key` - an object acting as a key for this user data value. This can be any object, for example a node or a string. If data for the given object and name already exists, it is overwritten.
        `name` - the name of the required property
        `data` - the value of the required property. If null is supplied, any existing entry for the key is removed.

    - #### getLocalIndexes

          public IntHashMap<java.util.Map<java.lang.Long,​KeyIndex>> getLocalIndexes()

      Get the table of local indexes supporting xsl:key (or implicit keys created by the optimizer). Indexes are held at Controller level (rather than being shared across transformations) if the key definition is dependent on local information, for example stylesheet parameters.
      Returns:
        the index of indexes. The master index is created if it does not already exist. The master index is a two-level index: the first level is indexed by the integer fingerprint of the key name; the second level is indexed by the document number (a long) for the specific document or temporary tree.

    - #### setRememberedNumber

          public void setRememberedNumber​(NodeInfo node,
                                          int number)

      Set the last remembered node, for node numbering purposes.

      This method is strictly for internal use only.

      Parameters:
        `node` - the node in question
        `number` - the number of this node

    - #### getRememberedNumber

          public int getRememberedNumber​(NodeInfo node)

      Get the number of a node if it is the last remembered one.

      This method is strictly for internal use only.

      Parameters:
        `node` - the node for which remembered information is required
      Returns:
        the number of this node if known, else -1.

    - #### checkReadiness

          protected void checkReadiness()
                                 throws XPathException

      Throws:
        `XPathException`

    - #### makeSourceTree

          public NodeInfo makeSourceTree​(javax.xml.transform.Source source,
                                         int validationMode)
                                  throws XPathException

      Make a source tree from a source supplied as a StreamSource or SAXSource
      Parameters:
        `source` - the source
        `validationMode` - indicates whether the source should be schema-validated
      Returns:
        the root of the constructed tree
      Throws:
        `XPathException` - if tree construction fails

    - #### prepareInputTree

          public NodeInfo prepareInputTree​(javax.xml.transform.Source source)

      Prepare an input tree for processing. This is used when either the initial input, or a Source returned by the document() function, is a NodeInfo or a DOMSource. The preparation consists of wrapping a DOM document inside a wrapper that implements the NodeInfo interface, and/or adding a space-stripping wrapper if the stylesheet strips whitespace nodes, and/or adding a type-stripping wrapper if the stylesheet strips input type annotations.

      This method is intended for internal use.

      Parameters:
        `source` - the input tree. Must be either a DOMSource or a NodeInfo
      Returns:
        the NodeInfo representing the input node, suitably wrapped. Exceptionally, the the source is a whitespace text node that is itself stripped, return null.

    - #### preEvaluateGlobals

          public void preEvaluateGlobals​(XPathContext context)
                                  throws XPathException

      Pre-evaluate global variables (when debugging/tracing).

      This method is intended for internal use.

      Parameters:
        `context` - the dynamic context for evaluating the global variables
      Throws:
        `XPathException`

    - #### registerGlobalVariableDependency

          public void registerGlobalVariableDependency​(GlobalVariable one,
                                                       GlobalVariable two)
                                                throws XPathException

      Register the dependency of one variable ("one") upon another ("two"), throwing an exception if this would establish a cycle of dependencies.
      Parameters:
        `one` - the first (dependent) variable
        `two` - the second (dependee) variable
      Throws:
        `XPathException` - if adding this dependency creates a cycle of dependencies among global variables.

    - #### setCurrentDateTime

          public void setCurrentDateTime​(DateTimeValue dateTime)
                                  throws XPathException

      Set the current date and time for this query or transformation. This method is provided primarily for testing purposes, to allow tests to be run with a fixed date and time. The supplied date/time must include a timezone, which is used as the implicit timezone.

      Note that comparisons of date/time values currently use the implicit timezone taken from the system clock, not from the value supplied here.

      Parameters:
        `dateTime` - the date/time value to be used as the current date and time
      Throws:
        `java.lang.IllegalStateException` - if a current date/time has already been established by calling getCurrentDateTime(), or by a previous call on setCurrentDateTime()
        `XPathException` - if the supplied dateTime contains no timezone

    - #### getCurrentDateTime

          public DateTimeValue getCurrentDateTime()

      Get the current date and time for this query or transformation. All calls during one transformation return the same answer.
      Returns:
        Get the current date and time. This will deliver the same value for repeated calls within the same transformation. The returned dateTime value will have a timezone, which will be the default/local timezone determined by the platform on which the application is running.

    - #### getImplicitTimezone

          public int getImplicitTimezone()

      Get the implicit timezone offset for this query or transformation
      Returns:
        the implicit timezone as an offset in minutes. This will be the default/local timezone determined by the platform on which the application is running. The value will be unchanged for repeated calls within the same transformation.

    - #### newXPathContext

          public XPathContextMajor newXPathContext()

      Make an XPathContext object for expression evaluation.

      This method is intended for internal use.

      Returns:
        the new XPathContext

    - #### setUseDocumentProjection

          public void setUseDocumentProjection​(PathMap pathMap)

      Indicate whether document projection should be used, and supply the PathMap used to control it. Note: this is available only under Saxon-EE.
      Parameters:
        `pathMap` - a path map to be used for projecting source documents

    - #### getPathMapForDocumentProjection

          public PathMap getPathMapForDocumentProjection()

      Get the path map used for document projection, if any.
      Returns:
        the path map to be used for document projection, if one has been supplied; otherwise null

    - #### getStylesheetCache

          public StylesheetCache getStylesheetCache()

      Get the cache of stylesheets (cached during calls on fn:transform()) for this query or transformation.
      Returns:
        the stylesheet cache

    - #### getFocusTrackerFactory

          public java.util.function.Function<SequenceIterator,​FocusTrackingIterator> getFocusTrackerFactory​(boolean multithreaded)

      Get the factory function that is used to create new instances of FocusTrackingIterator. The standard function for instantiating a FocusTrackingIterator can be overridden to deliver one with extra diagnostic capability for use in debuggers
      Parameters:
        `multithreaded` - true if the focus tracker must be suitable for executing a multi-threaded xsl:for-each iteration
      Returns:
        a factory function that is used to create FocusTrackingIterator instances

    - #### setFocusTrackerFactory

          public void setFocusTrackerFactory​(java.util.function.Function<SequenceIterator,​FocusTrackingIterator> focusTrackerFactory)

      Set a factory function that will be used to create new instances of FocusTrackingIterator. The standard function for instantiating a FocusTrackingIterator can be overridden to deliver one with extra diagnostic capability for use in debuggers.
      Parameters:
        `focusTrackerFactory` - a factory function that is used to create FocusTrackingIterator instances

    - #### setMultithreadedFocusTrackerFactory

          public void setMultithreadedFocusTrackerFactory​(java.util.function.Function<SequenceIterator,​FocusTrackingIterator> focusTrackerFactory)

      Set a factory function that will be used to create new instances of FocusTrackingIterator for multithreaded operation. The standard function for instantiating a FocusTrackingIterator can be overridden to deliver one with extra diagnostic capability for use in debuggers.
      Parameters:
        `focusTrackerFactory` - a factory function that is used to create FocusTrackingIterator instances

    - #### setMemoizingFocusTrackerFactory

          public void setMemoizingFocusTrackerFactory()

      Set the focus tracker factory function to a function that creates a memoizing focus tracker, which has the effect that all items read by the focus iterator are accessible to a debugger at any stage while iterating over the sequence