Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.sf.saxon
Class Controller

    java.lang.Object
      javax.xml.transform.Transformer
          net.sf.saxon.Controller

All Implemented Interfaces:
  InstructionInfoProvider

public class Controller
extends javax.xml.transform.Transformer
implements InstructionInfoProvider

The Controller is 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, as required by JAXP: 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.

The Controller can also be used when running Java applications that use neither XSLT nor XQuery. 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.

Wherever possible XSLT applications should use the JAXP Transformer class directly, rather than relying on Saxon-specific methods in the Controller. However, some features are currently available only through this class. This applies especially to new features specific to XSLT 2.0, since the JAXP interface still supports only XSLT 1.0. Such methods may be superseded in the future by JAXP methods.

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.

Since:
  8.4

Constructor Summary
`Controller(Configuration config)` Create a Controller and initialise variables.
`Controller(Configuration config, Executable executable)` Create a Controller and initialise variables.

Method Summary
`void` | `addTraceListener(TraceListener trace)` Adds the specified trace listener to receive trace events from this instance.
`boolean` | `checkUniqueOutputDestination(java.lang.String uri)` Check that an output destination has not been used before.
`void` | `clearDocumentPool()` Clear the document pool.
`void` | `clearParameters()` Reset the parameters to a null list.
`void` | `defineGlobalParameters(Bindery bindery)` Define the global parameters of the transformation or query.
`java.lang.String` | `getBaseOutputURI()` Get the base output URI.
`Bindery` | `getBindery()` Get the current bindery.
`java.lang.ClassLoader` | `getClassLoader()` Get the ClassLoader supplied using the method `setClassLoader(java.lang.ClassLoader)`.
`Configuration` | `getConfiguration()` Get the Configuration associated with this Controller.
`DateTimeValue` | `getCurrentDateTime()` Get the current date and time for this query or transformation.
`DocumentPool` | `getDocumentPool()` Get the document pool.
`javax.xml.transform.ErrorListener` | `getErrorListener()` Get the error listener.
`Executable` | `getExecutable()` Get the Executable object.
`InstructionInfo` | `getInstructionInfo()` Get diagnostic information about this context.
`KeyManager` | `getKeyManager()` Get the KeyManager.
`Emitter` | `getMessageEmitter()` Get the Emitter used for xsl:message output.
`NamePool` | `getNamePool()` Get the name pool in use.
`java.util.Properties` | `getOutputProperties()` Get the output properties for the transformation.
`java.lang.String` | `getOutputProperty(java.lang.String name)` Get the value of an output property.
`OutputURIResolver` | `getOutputURIResolver()` Get the output URI resolver.
`java.lang.Object` | `getParameter(java.lang.String expandedName)` Get a parameter to the transformation.
`javax.xml.transform.Result` | `getPrincipalResult()` Get the principal result destination.
`DocumentInfo` | `getPrincipalSourceDocument()` Get the principal source document.
`int` | `getRecoveryPolicy()` Get the policy for handling recoverable errors.
`int` | `getRememberedNumber(NodeInfo node)` Get the number of a node if it is the last remembered one.
`RuleManager` | `getRuleManager()` Get the Rule Manager.
`javax.xml.transform.URIResolver` | `getStandardURIResolver()` Get the fallback URI resolver.
`TraceListener` | `getTraceListener()` Get the TraceListener.
`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.
`void` | `initializeController()` Initialize the controller ready for a new transformation.
`boolean` | `isTracing()` Test whether instruction execution is being traced.
`Builder` | `makeBuilder()` Make a builder for the selected tree model.
`CharacterMapExpander` | `makeCharacterMapExpander(java.lang.String useMaps)` Make a CharacterMapExpander to handle the character map definitions in the serialization properties.
`Emitter` | `makeMessageEmitter()` Make an Emitter to be used for xsl:message output.
`PipelineConfiguration` | `makePipelineConfiguration()` Make a PipelineConfiguration based on the properties of this Controller.
`Stripper` | `makeStripper(Receiver b)` 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.
`javax.xml.transform.Result` | `prepareNextStylesheet(java.lang.String href, java.lang.String baseURI, javax.xml.transform.Result result)` Prepare another stylesheet to handle the output of this one.
`void` | `recoverableError(XPathException err)` Report a recoverable error.
`void` | `registerDocument(DocumentInfo doc, java.lang.String systemId)` Add a document to the document pool.
`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` | `setBaseOutputURI(java.lang.String uri)` Set the base output URI.
`void` | `setClassLoader(java.lang.ClassLoader loader)` Set a ClassLoader to be used when loading external classes.
`void` | `setCurrentDateTime(DateTimeValue dateTime)` Set the current date and time for this query or transformation.
`void` | `setErrorListener(javax.xml.transform.ErrorListener listener)` Set the error listener.
`void` | `setExecutable(Executable exec)` Associate this Controller with an Executable.
`void` | `setInitialMode(java.lang.String expandedModeName)` Set the initial mode for the transformation.
`void` | `setInitialTemplate(java.lang.String expandedName)` Set the initial named template to be used as the entry point.
`void` | `setMessageEmitter(Emitter emitter)` Set the Emitter to be used for xsl:message output.
`void` | `setOutputProperties(java.util.Properties properties)` Set the output properties for the transformation.
`void` | `setOutputProperty(java.lang.String name, java.lang.String value)` Set an output property for the transformation.
`void` | `setOutputURIResolver(OutputURIResolver resolver)` Set the URI resolver for secondary output documents.
`void` | `setParameter(java.lang.String expandedName, java.lang.Object value)` Set a parameter for the transformation.
`void` | `setPreparedStylesheet(PreparedStylesheet sheet)` Associate this Controller with a compiled stylesheet.
`void` | `setPrincipalSourceDocument(DocumentInfo doc)` Set the principal source document (used for evaluating global variables).
`void` | `setRememberedNumber(NodeInfo node, int number)` Set the last remembered node, for node numbering purposes.
`void` | `setRuleManager(RuleManager r)` Set the RuleManager, used to manage template rules for each mode.
`void` | `setTreeModel(int model)` Set the tree data model to use.
`void` | `setURIResolver(javax.xml.transform.URIResolver resolver)` Set an object that will be used to resolve URIs used in document(), etc.
`void` | `setUserData(java.lang.Object key, java.lang.String name, java.lang.Object data)` Set user data associated with a key.
`void` | `transform(javax.xml.transform.Source source, javax.xml.transform.Result result)` Perform a transformation from a Source document to a Result document.
`void` | `transformDocument(NodeInfo startNode, javax.xml.transform.Result result)` Transform a source XML document supplied as a tree.
`static NodeInfo` | `unravel(javax.xml.transform.Source source, Configuration config)` Get a NodeInfo corresponding to a DOM Node, either by wrapping or unwrapping the DOM Node.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Controller

    public Controller(Configuration config)

  Create a Controller and initialise variables. Constructor is protected, the Controller should be created using newTransformer() in the PreparedStylesheet class.

Parameters:
  `config` - The Configuration used by this Controller

### Controller

    public Controller(Configuration config,
                      Executable executable)

  Create a Controller and initialise variables. Constructor is protected, the Controller should be created using newTransformer() in the PreparedStylesheet class.

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

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

### setInitialMode

    public void setInitialMode(java.lang.String expandedModeName)

  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, that is "localname" if there is no namespace, or "{uri}localname" otherwise
  Since:
    8.4

### setOutputProperties

    public void setOutputProperties(java.util.Properties properties)

  Set the output properties for the transformation. These properties will override properties set in the templates with xsl:output.

  As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in `SaxonOutputKeys`. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

  Parameters:
    `properties` - the output properties to be used for the transformation. If the value is null, the properties are reset to be the properties of the Templates object (that is, for XSLT 2.0, the properties set in the unnamed xsl:output object).
  Since:
    8.4
  See Also:
    `SaxonOutputKeys`

### getOutputProperties

    public java.util.Properties getOutputProperties()

  Get the output properties for the transformation.

  As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in `SaxonOutputKeys`. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

  Returns:
    the output properties being used for the transformation, including properties defined in the stylesheet for the unnamed output format
  Since:
    8.4
  See Also:
    `SaxonOutputKeys`

### setOutputProperty

    public void setOutputProperty(java.lang.String name,
                                  java.lang.String value)

  Set an output property for the transformation.

  As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in `SaxonOutputKeys`. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

  Parameters:
    `name` - the name of the property
    `value` - the value of the property
  Since:
    8.4
  See Also:
    `SaxonOutputKeys`

### getOutputProperty

    public java.lang.String getOutputProperty(java.lang.String name)

  Get the value of an output property.

  As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in `SaxonOutputKeys`. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

  Parameters:
    `name` - the name of the requested property
  Returns:
    the value of the requested property
  Since:
    8.4
  See Also:
    `SaxonOutputKeys`

### setBaseOutputURI

    public void setBaseOutputURI(java.lang.String uri)

  Set the base output URI. This defaults to the system ID of the principal Result object, but a different value can be set for use where there is no principal result. The command line interface sets this to the current working directory.

  The concept of the base output URI is new in XSLT 2.0: it defines the base URI for resolving relative URIs in the `href` attribute of the `xsl:result-document` instruction. This method may be superseded by a standard JAXP method when JAXP is updated to support XSLT 2.0.

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

### getBaseOutputURI

    public java.lang.String getBaseOutputURI()

  Get the base output URI. This defaults to the system ID of the principal Result object, but a different value can be set for use where there is no principal result. The command line interface sets this to the current working directory.

  The concept of the base output URI is new in XSLT 2.0: it defines the base URI for resolving relative URIs in the `href` attribute of the `xsl:result-document` instruction. This method may be superseded by a standard JAXP method when JAXP is updated to support XSLT 2.0.

  Returns:
    the base output URI
  Since:
    8.4

### getPrincipalResult

    public javax.xml.transform.Result getPrincipalResult()

  Get the principal result destination.

  This method is intended for internal use only.

### checkUniqueOutputDestination

    public boolean checkUniqueOutputDestination(java.lang.String uri)

  Check that an output destination has not been used before.

  This method is intended for internal use only.

### setInitialTemplate

    public void setInitialTemplate(java.lang.String expandedName)
                            throws XPathException

  Set the initial named template to be used as the entry point.

  XSLT 2.0 allows a transformation to start by executing a named template, rather than by matching an initial context node in a source document. This method may eventually be superseded by a standard JAXP method once JAXP supports XSLT 2.0.

  Although the Saxon command line interface does not allow both a source document and an initial template to be specified, this API has no such restriction.

  Note that any parameters supplied using `setParameter(java.lang.String, java.lang.Object)` are used as the values of global stylesheet parameters. There is no way to supply values for local parameters of the initial template.

  Parameters:
    `expandedName` - The expanded name of the template in {uri}local format
  Throws:
    `XPathException` - if there is no named template with this name
  Since:
    8.4

### 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 for use in conjunction with the experimental pull API.

### makeMessageEmitter

    public Emitter makeMessageEmitter()
                               throws XPathException

  Make an Emitter to be used for xsl:message output.

  This method is intended for internal use only.

  Returns:
    The newly constructed message Emitter
  Throws:
    `XPathException` - if any dynamic error occurs; in particular, if the registered MessageEmitter class is not an Emitter

### setMessageEmitter

    public void setMessageEmitter(Emitter emitter)

  Set the Emitter 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 yet 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.

  This method is intended for use by advanced applications. The Emitter interface itself is not part of the stable Saxon public API.

  Parameters:
    `emitter` - The emitter to receive xsl:message output.

### getMessageEmitter

    public Emitter getMessageEmitter()

  Get the Emitter used for xsl:message output. This returns the emitter previously supplied to the `setMessageEmitter(net.sf.saxon.event.Emitter)` method, or the default message emitter otherwise.

  Returns:
    the Emitter being used for xsl:message output

### makeCharacterMapExpander

    public CharacterMapExpander makeCharacterMapExpander(java.lang.String useMaps)
                                                  throws XPathException

  Make a CharacterMapExpander to handle the character map definitions in the serialization properties.

  This method is intended for internal use only.

  Parameters:
    `useMaps` - the expanded use-character-maps property: a space-separated list of names of character maps to be used, each one expressed as an expanded-QName in Clark notation (that is, {uri}local-name).
  Returns:
    a CharacterMapExpander if one is required, or null if not (for example, if the useMaps argument is an empty string).
  Throws:
    `XPathException` - if a name in the useMaps property cannot be resolved to a declared character map.

### getRecoveryPolicy

    public int getRecoveryPolicy()

  Get the policy for handling recoverable errors.

  This method is intended for internal use

  Returns:
    the current policy. This is obtained from the error listener; if the error listener is not a StandardErrorListener, the value RECOVER_WITH_WARNINGS is returned.

### setErrorListener

    public void setErrorListener(javax.xml.transform.ErrorListener listener)

  Set the error listener.

  Parameters:
    `listener` - the ErrorListener to be used

### getErrorListener

    public javax.xml.transform.ErrorListener getErrorListener()

  Get the error listener.

  Returns:
    the ErrorListener in use

### recoverableError

    public void recoverableError(XPathException err)
                          throws DynamicError

  Report a recoverable error. This is an XSLT concept: by default, such an error results in a warning message, and processing continues. In XQuery, however, there are no recoverable errors so a fatal error is reported.

  This method is intended for internal use only.

  Parameters:
    `err` - An exception holding information about the error
  Throws:
    `DynamicError` - if the error listener decides not to recover from the error

### reportFatalError

    public void reportFatalError(XPathException err)

  Report a fatal error

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

### setPrincipalSourceDocument

    public void setPrincipalSourceDocument(DocumentInfo doc)

  Set the principal source document (used for evaluating global variables). When a transformation is invoked using the `transform(javax.xml.transform.Source, javax.xml.transform.Result)` method, the principal source document is set automatically. This method is useful in XQuery, to define an initial context node for evaluating global variables, and also in XSLT 2.0, when the transformation is started by invoking a named template.

  Parameters:
    `doc` - The principal source document
  Since:
    8.4

### getBindery

    public Bindery getBindery()

  Get the current bindery.

  This method is intended for internal use only.

  Returns:
    the Bindery (in which values of all variables are held)

### getPrincipalSourceDocument

    public DocumentInfo getPrincipalSourceDocument()

  Get the principal source document. This returns the document previously supplied to the `setPrincipalSourceDocument(net.sf.saxon.om.DocumentInfo)` method, or the principal source document set implicitly using methods such as `transform(javax.xml.transform.Source, javax.xml.transform.Result)`.

  Returns:
    the principal source document
  Since:
    8.4

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

### setOutputURIResolver

    public void setOutputURIResolver(OutputURIResolver resolver)

  Set the URI resolver for secondary output documents.

  XSLT 2.0 introduces the `xsl:result-document` This method may eventually be superseded by a standard JAXP method.

  Parameters:
    `resolver` - An object that implements the OutputURIResolver interface, or null.
  Since:
    8.4

### 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
  See Also:
    `setOutputURIResolver(net.sf.saxon.OutputURIResolver)`

### getKeyManager

    public KeyManager getKeyManager()

  Get the KeyManager.

  This method is intended for internal use only.

  Returns:
    the KeyManager, which holds details of all key declarations

### getNamePool

    public NamePool getNamePool()

  Get the name pool in use. The name pool is responsible for mapping QNames used in source documents and compiled stylesheets and queries into numeric codes. All source documents used by a given transformation or query must use the same name pool as the compiled stylesheet or query.

  Returns:
    the name pool in use
  Since:
    8.4

### setTreeModel

    public void setTreeModel(int model)

  Set the tree data model to use. This affects all source documents subsequently constructed using a Builder obtained from this Controller. This includes a document built from a StreamSource or SAXSource supplied as a parameter to the `transform(javax.xml.transform.Source, javax.xml.transform.Result)` method.

  Parameters:
    `model` - the required tree model: `Builder.STANDARD_TREE` or `Builder.TINY_TREE`
  Since:
    8.4
  See Also:
    `Builder`

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

### makeStripper

    public Stripper makeStripper(Receiver b)

  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` `Configuration.setStripsAllWhiteSpace(boolean)`.

  Parameters:
    `b` - 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

### registerDocument

    public void registerDocument(DocumentInfo doc,
                                 java.lang.String systemId)

  Add a document to the document pool.

  This method is intended for internal use only.

  Parameters:
    `doc` - the root node of the document to be added
    `systemId` - thesystem ID of this document

### setRuleManager

    public void setRuleManager(RuleManager r)

  Set the RuleManager, used to manage template rules for each mode.

  This method is intended for internal use only.

  Parameters:
    `r` - the Rule Manager

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

### 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.trace.TraceListener)`. If more than one TraceListener has been added, this method will return a composite TraceListener. Because this 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

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

### setPreparedStylesheet

    public void setPreparedStylesheet(PreparedStylesheet sheet)

  Associate this Controller with a compiled stylesheet.

  This method is intended for internal use only.

  Parameters:
    `sheet` - the compiled stylesheet

### setExecutable

    public void setExecutable(Executable exec)

  Associate this Controller with an Executable. This method is used by the XQuery processor. The Executable object is overkill in this case - the only thing it currently holds are copies of the collation table.

  This method is intended for internal use only

  Parameters:
    `exec` - the Executable

### initializeController

    public void initializeController()
                              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.

  Throws:
    `XPathException`

### defineGlobalParameters

    public void defineGlobalParameters(Bindery bindery)
                                throws XPathException

  Define the global parameters of the transformation or query.

  This method is intended for internal use only

  Parameters:
    `bindery` - The Bindery, which holds values of global variables and parameters
  Throws:
    `XPathException`

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

### transform

    public void transform(javax.xml.transform.Source source,
                          javax.xml.transform.Result result)
                   throws javax.xml.transform.TransformerException

  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.
    `result` - The destination for the result tree.
  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".
    `javax.xml.transform.TransformerException`

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

  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.

### unravel

    public static NodeInfo unravel(javax.xml.transform.Source source,
                                   Configuration config)

  Get a NodeInfo corresponding to a DOM Node, either by wrapping or unwrapping the DOM Node.

  This method is intended for internal use.

### transformDocument

    public void transformDocument(NodeInfo startNode,
                                  javax.xml.transform.Result result)
                           throws javax.xml.transform.TransformerException

  Transform a source XML document supplied as a tree.
  A new output destination should be created for each source document, by using setOutputDetails().

  This method is intended for internal use. External applications should use the `transform(javax.xml.transform.Source, javax.xml.transform.Result)` method, which is part of the JAXP interface. Note that `NodeInfo` implements the JAXP `Source` interface, so it may be supplied directly to the transform() method.

  Parameters:
    `startNode` - A Node that identifies the source document to be transformed and the node where the transformation should start. May be null if the transformation is to start using an initial template.
    `result` - The output destination
  Throws:
    `XPathException` - if any dynamic error occurs
    `javax.xml.transform.TransformerException`

### preEvaluateGlobals

    public void preEvaluateGlobals(XPathContext context)
                            throws XPathException

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

  This method is intended for internal use.

  Throws:
    `XPathException`

### prepareNextStylesheet

    public javax.xml.transform.Result prepareNextStylesheet(java.lang.String href,
                                                            java.lang.String baseURI,
                                                            javax.xml.transform.Result result)
                                                     throws javax.xml.transform.TransformerException

  Prepare another stylesheet to handle the output of this one.

  This method is intended for internal use, to support the `saxon:next-in-chain` extension.

  Parameters:
    `href` - URI of the next stylesheet to be applied
    `baseURI` - base URI for resolving href if it's a relative URI
    `result` - the output destination of the current stylesheet
  Returns:
    a replacement destination for the current stylesheet
  Throws:
    `XPathException` - if any dynamic error occurs
    `javax.xml.transform.TransformerException`

### setParameter

    public void setParameter(java.lang.String expandedName,
                             java.lang.Object value)

  Set a parameter for the transformation.

  The following table shows some of the classes that are supported by this method. (Others may also be supported, but continued support is not guaranteed.) Each entry in the table shows first the Java class of the supplied object, and then the type of the resulting XPath value.

  Java Class | XPath 2.0 type
  --- | ---
  String | xs:string
  Boolean | xs:boolean
  Integer | xs:integer
  Long | xs:integer
  Double | xs:double
  Float | xs:float
  BigDecimal | xs:decimal
  BigInteger | xs:integer
  Date | xs:dateTime
  Array or List of any of the above | sequence of the above
  null | empty sequence

  A node may be supplied as a `NodeInfo` object, a sequence of nodes as an array or List of `NodeInfo` objects.

  In addition, any object that implements the Saxon `Value` interface may be supplied, and will be used without conversion.

  A node belong to an external object model (such as DOM, JDOM, or XOM) may be supplied provided (a) that the external object model is registered with the Configuration, and (b) that the node is part of a document tree that has been registered in the document pool.

  Parameters:
    `expandedName` - The name of the parameter in {uri}local format
    `value` - The value object. This must follow the rules above. Other formats in addition to those listed above may be accepted.
  Since:
    8.4

### clearParameters

    public void clearParameters()

  Reset the parameters to a null list.

### getParameter

    public java.lang.Object getParameter(java.lang.String expandedName)

  Get a parameter to the transformation. This returns the value of a parameter that has been previously set using the `setParameter(java.lang.String, java.lang.Object)` method. The value is returned exactly as supplied, that is, before any conversion to an XPath value.

  Parameters:
    `expandedName` - the name of the required parameter, in "{uri}local-name" format
  Returns:
    the value of the parameter, if it exists, or null otherwise

### 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. Calls are ignored if a current date/time has already been established by calling getCurrentDateTime().

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

  Throws:
    `XPathException`

### getCurrentDateTime

    public DateTimeValue getCurrentDateTime()

  Get the current date and time for this query or transformation. All calls during one transformation return the same answer.

  This method is intended for internal use.

  Returns:
    Get the current date and time. This will deliver the same value 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

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

### getInstructionInfo

    public InstructionInfo getInstructionInfo()

  Get diagnostic information about this context.

  This method is intended for internal use.

  Specified by:
    `getInstructionInfo` in interface `InstructionInfoProvider`

### setClassLoader

    public void setClassLoader(java.lang.ClassLoader loader)

  Set a ClassLoader to be used when loading external classes. Examples of classes that are loaded include SAX parsers, localization modules for formatting numbers and dates, extension functions, external object models. In an environment such as Eclipse that uses its own ClassLoader, this ClassLoader should be nominated to ensure that any class loaded by Saxon is identical to a class of the same name loaded by the external environment.

  This method is for application use, but is experimental and subject to change.

  Parameters:
    `loader` - the ClassLoader to be used.

### getClassLoader

    public java.lang.ClassLoader getClassLoader()

  Get the ClassLoader supplied using the method `setClassLoader(java.lang.ClassLoader)`. If none has been supplied, return null.

  This method is for application use, but is experimental and subject to change.

  Returns:
    the ClassLoader in use.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD