Controller
Date: 2016-07-03

com.icl.saxon

## Class Controller

- java.lang.Object
- - javax.xml.transform.Transformer
  - - com.icl.saxon.Controller

- All Implemented Interfaces:
    NodeOrderComparer

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

  Controller processes an XML file, calling registered node handlers when appropriate to process its elements, character content, and attributes.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DO_NOT_RECOVER`
    `static int` | `RECOVER_SILENTLY`
    `static int` | `RECOVER_WITH_WARNINGS`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `Controller()` Default constructor is provided for Java-only programs, i.e.
    `protected` | `Controller(TransformerFactoryImpl factory)` Create a Controller and initialise variables.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addTraceListener(TraceListener trace)` Adds the specified trace listener to receive trace events from this instance.
    `void` | `applyImports(Context c, Mode mode, int min, int max, ParameterSet params)` Apply a template imported from the stylesheet containing the current template
    `void` | `applyTemplates(Context c, Expression select, Mode mode, ParameterSet parameters)` ApplyTemplates to process selected nodes using the handlers registered for a particular mode.
    `void` | `changeOutputDestination(java.util.Properties props, javax.xml.transform.Result result)` Set a new output destination, supplying the output format details.
    `void` | `changeToTextOutputDestination(java.lang.StringBuffer buffer)` Set a simple StringBuffer output destination.
    `void` | `clearDocumentPool()` Clear the document pool.
    `void` | `clearParameters()` Reset the parameters to a null list.
    `int` | `compare(NodeInfo n1, NodeInfo n2)` Compare the position of two nodes in document order
    `void` | `disableWhitespaceStripping(boolean disable)` Disable whitespace stripping
    `Bindery` | `getBindery()` Get the current bindery
    `DecimalFormatManager` | `getDecimalFormatManager()`
    `DocumentPool` | `getDocumentPool()` Get the document pool.
    `javax.xml.transform.ErrorListener` | `getErrorListener()` Get the error listener
    `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
    `Outputter` | `getOutputter()` Get the current outputter
    `java.lang.Object` | `getParameter(java.lang.String expandedName)` Get a parameter to the transformation
    `int` | `getRecoveryPolicy()` Get the policy for handling recoverable errors
    `RuleManager` | `getRuleManager()`
    `javax.xml.transform.URIResolver` | `getStandardURIResolver()` Get the fallback URI resolver.
    `TraceListener` | `getTraceListener()`
    `TransformerFactoryImpl` | `getTransformerFactory()`
    `int` | `getTreeModel()` Get the tree model in use
    `javax.xml.transform.URIResolver` | `getURIResolver()` Get the primary URI resolver.
    `java.lang.Object` | `getUserData(NodeInfo node, java.lang.String name)` Get the named user data property for the node
    `boolean` | `isLineNumbering()` Determine whether line numbering is enabled
    `boolean` | `isTracing()`
    `boolean` | `isWhitespaceStrippingDisabled()` Determine if whitespace stripping is disabled
    `Builder` | `makeBuilder()` Make a builder for the selected tree model
    `Context` | `makeContext(NodeInfo node)` Create a new context with a given node as the current node and the only node in the current node list.
    `Emitter` | `makeMessageEmitter()` Make an Emitter to be used for xsl:message output
    `Stripper` | `makeStripper(Builder b)`
    `void` | `pauseTracing(boolean pause)`
    `void` | `removeTraceListener(TraceListener trace)` Removes the specified trace listener so that the next invocation of the render method will not send trace events to the listener.
    `void` | `reportRecoverableError(java.lang.String message, javax.xml.transform.SourceLocator location)` Report a recoverable error
    `void` | `reportRecoverableError(javax.xml.transform.TransformerException err)` Report a recoverable error
    `void` | `reset()` Reset this `Transformer` to its original configuration.
    `void` | `resetOutputDestination(Outputter outputter)` Close the current outputter, and revert to the previous outputter.
    `void` | `run(NodeInfo node)` Process a Document.
    `void` | `setDecimalFormatManager(DecimalFormatManager manager)`
    `void` | `setDiagnosticName(java.lang.String name)` Set a diagnostic name for this transformation (accessible through toString())
    `void` | `setErrorListener(javax.xml.transform.ErrorListener listener)` Set the error listener
    `void` | `setLineNumbering(boolean onOrOff)` Set line numbering (of the source document) on or off
    `void` | `setMessageEmitter(Emitter emitter)` Set the Emitter to be used for xsl:message output
    `void` | `setNamePool(NamePool pool)` Set the name pool to be used
    `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` | `setParameter(java.lang.String expandedName, java.lang.Object value)` Set a parameter for the transformation.
    `void` | `setParams(ParameterSet params)` Set parameters supplied externally (typically, on the command line).
    `void` | `setPreparedStyleSheet(PreparedStyleSheet sheet)` Associate this Controller with a compiled stylesheet
    `void` | `setRecoveryPolicy(int policy)` Set the policy for handling recoverable errors
    `void` | `setRuleManager(RuleManager r)`
    `void` | `setTraceListener(TraceListener trace)`
    `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(NodeInfo node, java.lang.String name, java.lang.Object data)` Set a user data property for a node.
    `java.lang.String` | `toString()`
    `void` | `transform(javax.xml.transform.Source source, javax.xml.transform.Result result)` Process the source tree to SAX parse events.
    `void` | `transformDocument(NodeInfo startNode, javax.xml.transform.Result result)` Render a source XML document supplied as a tree.
    `protected boolean` | `usesPreviewMode()` Does this transformation use preview mode?

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

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

- - ### Field Detail

    - #### RECOVER_SILENTLY

          public static final int RECOVER_SILENTLY

      See Also:
        Constant Field Values

    - #### RECOVER_WITH_WARNINGS

          public static final int RECOVER_WITH_WARNINGS

      See Also:
        Constant Field Values

    - #### DO_NOT_RECOVER

          public static final int DO_NOT_RECOVER

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Controller

          public Controller()

      Default constructor is provided for Java-only programs, i.e. applications that use the RuleManager to set up Java handlers for nodes, without using a stylesheet

    - #### Controller

          protected Controller(TransformerFactoryImpl factory)

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

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

      NOTE: the Saxon implementation of this method does not clear the document pool. This is because the reason for resetting an existing Transformer rather than creating a new one is to reuse resources, and the document pool is the most important resource held by the Transformer. If there is a requirement to clear the document pool, then it is possible either (a) to call the `clearDocumentPool()` method, or (b) to create a new Transformer.

      Overrides:
        `reset` in class `javax.xml.transform.Transformer`
      Since:
        1.5

    - #### getTransformerFactory

          public TransformerFactoryImpl getTransformerFactory()

    - #### setDiagnosticName

          public void setDiagnosticName(java.lang.String name)

      Set a diagnostic name for this transformation (accessible through toString())

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### run

          public void run(NodeInfo node)
                   throws javax.xml.transform.TransformerException

      Process a Document.

      This method is intended for use when performing a pure Java transformation, without a stylesheet. Where there is an XSLT stylesheet, use transformDocument() or transform() instead: those methods set up information from the stylesheet before calling run().

      The process starts by calling the registered node handler to process the supplied node. Note that the same document can be processed any number of times, typically with different node handlers for each pass. The NodeInfo will typically be the root of a tree built using com.icl.saxon.om.Builder.

      Throws:
        `javax.xml.transform.TransformerException`

    - #### applyTemplates

          public void applyTemplates(Context c,
                            Expression select,
                            Mode mode,
                            ParameterSet parameters)
                              throws javax.xml.transform.TransformerException

      ApplyTemplates to process selected nodes using the handlers registered for a particular mode.
      Parameters:
        `select` - A node-set expression (or more accurately a node-list) that determines which nodes are selected. Note: if the nodes are to be sorted, the select Expression will take care of this.
        `mode` - Identifies the processing mode. It should match the mode defined when the element handler was registered using setHandler with a mode parameter. Set this parameter to null to invoke the default mode.
        `parameters` - A ParameterSet containing the parameters to the handler/template being invoked. Specify null if there are no parameters.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### applyImports

          public void applyImports(Context c,
                          Mode mode,
                          int min,
                          int max,
                          ParameterSet params)
                            throws javax.xml.transform.TransformerException

      Apply a template imported from the stylesheet containing the current template
      Throws:
        `javax.xml.transform.TransformerException`

    - #### compare

          public int compare(NodeInfo n1,
                    NodeInfo n2)

      Compare the position of two nodes in document order
      Specified by:
        `compare` in interface `NodeOrderComparer`
      Parameters:
        `n1` - The first node
        `n2` - The second node
      Returns:
        <0 if the first node is first in document order; >0 if the second node comes first in document order; 0 if the two parameters identify the same node

    - #### 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.
      Specified by:
        `setOutputProperties` in class `javax.xml.transform.Transformer`

    - #### getOutputProperties

          public java.util.Properties getOutputProperties()

      Get the output properties for the transformation.
      Specified by:
        `getOutputProperties` in class `javax.xml.transform.Transformer`

    - #### setOutputProperty

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

      Set an output property for the transformation.
      Specified by:
        `setOutputProperty` in class `javax.xml.transform.Transformer`

    - #### getOutputProperty

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

      Get the value of an output property
      Specified by:
        `getOutputProperty` in class `javax.xml.transform.Transformer`

    - #### changeOutputDestination

          public void changeOutputDestination(java.util.Properties props,
                                     javax.xml.transform.Result result)
                                       throws javax.xml.transform.TransformerException

      Set a new output destination, supplying the output format details.
      This affects all further output until resetOutputDestination() is called. Note that it is the caller's responsibility to close the Writer after use.
      Parameters:
        `props` - Details of the new output format
        `result` - Details of the new output destination
      Throws:
        `javax.xml.transform.TransformerException`

    - #### changeToTextOutputDestination

          public void changeToTextOutputDestination(java.lang.StringBuffer buffer)

      Set a simple StringBuffer output destination. Used during calls to xsl:attribute, xsl:comment, xsl:processing-instruction

    - #### getOutputter

          public Outputter getOutputter()

      Get the current outputter

    - #### resetOutputDestination

          public void resetOutputDestination(Outputter outputter)
                                      throws javax.xml.transform.TransformerException

      Close the current outputter, and revert to the previous outputter.
      Parameters:
        `outputter` - The outputter to revert to
      Throws:
        `javax.xml.transform.TransformerException`

    - #### makeMessageEmitter

          public Emitter makeMessageEmitter()
                                     throws javax.xml.transform.TransformerException

      Make an Emitter to be used for xsl:message output
      Throws:
        `javax.xml.transform.TransformerException`

    - #### setMessageEmitter

          public void setMessageEmitter(Emitter emitter)

      Set the Emitter to be used for xsl:message output

    - #### getMessageEmitter

          public Emitter getMessageEmitter()

      Get the Emitter used for xsl:message output

    - #### setRecoveryPolicy

          public void setRecoveryPolicy(int policy)

      Set the policy for handling recoverable errors

    - #### getRecoveryPolicy

          public int getRecoveryPolicy()

      Get the policy for handling recoverable errors

    - #### setErrorListener

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

      Set the error listener
      Specified by:
        `setErrorListener` in class `javax.xml.transform.Transformer`

    - #### getErrorListener

          public javax.xml.transform.ErrorListener getErrorListener()

      Get the error listener
      Specified by:
        `getErrorListener` in class `javax.xml.transform.Transformer`

    - #### reportRecoverableError

          public void reportRecoverableError(java.lang.String message,
                                    javax.xml.transform.SourceLocator location)
                                      throws javax.xml.transform.TransformerException

      Report a recoverable error
      Throws:
        `javax.xml.transform.TransformerException` - if the error listener decides not to recover from the error

    - #### reportRecoverableError

          public void reportRecoverableError(javax.xml.transform.TransformerException err)
                                      throws javax.xml.transform.TransformerException

      Report a recoverable error
      Throws:
        `javax.xml.transform.TransformerException` - if the error listener decides not to recover from the error

    - #### getDocumentPool

          public DocumentPool getDocumentPool()

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

    - #### clearDocumentPool

          public void clearDocumentPool()

      Clear the document pool. This is sometimes useful when 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.

    - #### setLineNumbering

          public void setLineNumbering(boolean onOrOff)

      Set line numbering (of the source document) on or off

    - #### isLineNumbering

          public boolean isLineNumbering()

      Determine whether line numbering is enabled

    - #### makeContext

          public Context makeContext(NodeInfo node)

      Create a new context with a given node as the current node and the only node in the current node list.

    - #### getBindery

          public Bindery getBindery()

      Get the current bindery

    - #### getURIResolver

          public javax.xml.transform.URIResolver getURIResolver()

      Get the primary URI resolver.
      Specified by:
        `getURIResolver` in class `javax.xml.transform.Transformer`
      Returns:
        the user-supplied URI resolver if there is one, or the system-defined one otherwise (Note, this isn't quite as JAXP specifies it).

    - #### getStandardURIResolver

          public javax.xml.transform.URIResolver getStandardURIResolver()

      Get the fallback URI resolver.
      Returns:
        the the system-defined URIResolver

    - #### getKeyManager

          public KeyManager getKeyManager()

      Get the KeyManager

    - #### setNamePool

          public void setNamePool(NamePool pool)

      Set the name pool to be used

    - #### getNamePool

          public NamePool getNamePool()

      Get the name pool in use

    - #### setTreeModel

          public void setTreeModel(int model)

      Set the tree data model to use

    - #### getTreeModel

          public int getTreeModel()

      Get the tree model in use

    - #### disableWhitespaceStripping

          public void disableWhitespaceStripping(boolean disable)

      Disable whitespace stripping

    - #### isWhitespaceStrippingDisabled

          public boolean isWhitespaceStrippingDisabled()

      Determine if whitespace stripping is disabled

    - #### makeBuilder

          public Builder makeBuilder()

      Make a builder for the selected tree model

    - #### makeStripper

          public Stripper makeStripper(Builder b)

    - #### setDecimalFormatManager

          public void setDecimalFormatManager(DecimalFormatManager manager)

    - #### getDecimalFormatManager

          public DecimalFormatManager getDecimalFormatManager()

    - #### setRuleManager

          public void setRuleManager(RuleManager r)

    - #### getRuleManager

          public RuleManager getRuleManager()

    - #### setTraceListener

          public void setTraceListener(TraceListener trace)

    - #### getTraceListener

          public TraceListener getTraceListener()

    - #### isTracing

          public final boolean isTracing()

    - #### pauseTracing

          public void pauseTracing(boolean pause)

    - #### setPreparedStyleSheet

          public void setPreparedStyleSheet(PreparedStyleSheet sheet)

      Associate this Controller with a compiled stylesheet

    - #### usesPreviewMode

          protected boolean usesPreviewMode()

      Does this transformation use preview mode?

    - #### addTraceListener

          public void addTraceListener(TraceListener trace)

      Adds the specified trace listener to receive trace events from this instance. Must be called before the invocation of the render method.
      Parameters:
        `trace` - the trace listener.

    - #### removeTraceListener

          public void removeTraceListener(TraceListener trace)

      Removes the specified trace listener so that the next invocation of the render method will not send trace events to the listener.
      Parameters:
        `trace` - the trace listener.

    - #### getUserData

          public java.lang.Object getUserData(NodeInfo node,
                                     java.lang.String name)

      Get the named user data property for the node
      Parameters:
        `name` - the name of the user data property to return
      Returns:
        The value of the named user data property. Returns null if no property of that name has been set using setUserData() for this NodeInfo object.

    - #### setUserData

          public void setUserData(NodeInfo node,
                         java.lang.String name,
                         java.lang.Object data)

      Set a user data property for a node.
      Parameters:
        `name` - The name of the user data property to be set. Any existing user data property of the same name will be overwritten.
        `data` - an object to be saved with this element, which can be retrieved later using getUserData().

    - #### transform

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

      Process the source tree to SAX parse events.
      Specified by:
        `transform` in class `javax.xml.transform.Transformer`
      Parameters:
        `source` - The input for the source tree.
        `result` - The destination for the result tree.
      Throws:
        `javax.xml.transform.TransformerException` - if the transformation fails. As a special case, the method throws a TerminationException (a subclass of TransformerException) if the transformation was terminated using xsl:message terminate="yes".

    - #### transformDocument

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

      Render a source XML document supplied as a tree.
      A new output destination should be created for each source document, by using setOutputDetails().
      Parameters:
        `startNode` - A Node that identifies the source document to be transformed and the node where the transformation should start
        `result` - The output destination
      Throws:
        `javax.xml.transform.TransformerException`

    - #### setParameter

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

      Set a parameter for the transformation.
      Specified by:
        `setParameter` in class `javax.xml.transform.Transformer`
      Parameters:
        `expandedName` - The name of the parameter in {uri}local format
        `value` - The value object. This can be any valid Java object it follows the same conversion rules as a value returned from a Saxon extension function.

    - #### setParams

          public void setParams(ParameterSet params)

      Set parameters supplied externally (typically, on the command line). (non-TRAX method retained for backwards compatibility)
      Parameters:
        `params` - A ParameterSet containing the (name, value) pairs.

    - #### clearParameters

          public void clearParameters()

      Reset the parameters to a null list.
      Specified by:
        `clearParameters` in class `javax.xml.transform.Transformer`

    - #### getParameter

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

      Get a parameter to the transformation
      Specified by:
        `getParameter` in class `javax.xml.transform.Transformer`

    - #### setURIResolver

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

      Set an object that will be used to resolve URIs used in document(), etc.
      Specified by:
        `setURIResolver` in class `javax.xml.transform.Transformer`
      Parameters:
        `resolver` - An object that implements the URIResolver interface, or null.