## com.icl.saxon
Class Controller

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

All Implemented Interfaces:
  NodeOrderComparer

public class Controller
extends Transformer
implements NodeOrderComparer

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

Field Summary
`static int` `DO_NOT_RECOVER`
`static int` `RECOVER_SILENTLY`
`static int` `RECOVER_WITH_WARNINGS`

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

Method Summary
`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, 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.
`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()`
`URIResolver` `getStandardURIResolver()` Get the fallback URI resolver.
`TraceListener` `getTraceListener()`
`TransformerFactoryImpl` `getTransformerFactory()`
`int` `getTreeModel()` Get the tree model in use
`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
`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, SourceLocator location)` Report a recoverable error
`void` `reportRecoverableError(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(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(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(Source source, Result result)` Process the source tree to SAX parse events.
`void` `transformDocument(NodeInfo startNode, 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 `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()

### run

    public void run(NodeInfo node)
             throws 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:
    `TransformerException`

### applyTemplates

    public void applyTemplates(Context c,
                               Expression select,
                               Mode mode,
                               ParameterSet parameters)
                        throws 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:
    `TransformerException`

### applyImports

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

  Apply a template imported from the stylesheet containing the current template

  Throws:
    `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 `Transformer`
  Parameters:
    `properties` - A set of output properties that will be used to override any of the same properties in affect for the transformation.
  See Also:
    `OutputKeys`, `Properties`

### getOutputProperties

    public java.util.Properties getOutputProperties()

  Get the output properties for the transformation.

  Specified by:
    `getOutputProperties` in class `Transformer`
  Returns:
    A copy of the set of output properties in effect for the next transformation.
  See Also:
    `OutputKeys`, `Properties`, XSL Transformations (XSLT) Version 1.0

### setOutputProperty

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

  Set an output property for the transformation.

  Specified by:
    `setOutputProperty` in class `Transformer`
  Parameters:
    `name` - A non-null String that specifies an output property name, which may be namespace qualified.
    `value` - The non-null string value of the output property.
  See Also:
    `OutputKeys`

### getOutputProperty

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

  Get the value of an output property

  Specified by:
    `getOutputProperty` in class `Transformer`
  Parameters:
    `name` - A non-null String that specifies an output property name, which may be namespace qualified.
  Returns:
    The string value of the output property, or null if no property was found.
  See Also:
    `OutputKeys`

### changeOutputDestination

    public void changeOutputDestination(java.util.Properties props,
                                        Result result)
                                 throws 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:
    `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 TransformerException

  Close the current outputter, and revert to the previous outputter.

  Parameters:
    `outputter` - The outputter to revert to
  Throws:
    `TransformerException`

### makeMessageEmitter

    public Emitter makeMessageEmitter()
                               throws TransformerException

  Make an Emitter to be used for xsl:message output

  Throws:
    `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(ErrorListener listener)

  Set the error listener

  Specified by:
    `setErrorListener` in class `Transformer`
  Parameters:
    `listener` - The new error listener.

### getErrorListener

    public ErrorListener getErrorListener()

  Get the error listener

  Specified by:
    `getErrorListener` in class `Transformer`
  Returns:
    The current error handler, which should never be null.

### reportRecoverableError

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

  Report a recoverable error

  Throws:
    `TransformerException` - if the error listener decides not to recover from the error

### reportRecoverableError

    public void reportRecoverableError(TransformerException err)
                                throws TransformerException

  Report a recoverable error

  Throws:
    `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 URIResolver getURIResolver()

  Get the primary URI resolver.

  Specified by:
    `getURIResolver` in class `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 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

### 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(Source source,
                          Result result)
                   throws TransformerException

  Process the source tree to SAX parse events.

  Specified by:
    `transform` in class `Transformer`
  Parameters:
    `source` - The input for the source tree.
    `result` - The destination for the result tree.
  Throws:
    `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,
                                  Result result)
                           throws 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:
    `TransformerException`

### setParameter

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

  Set a parameter for the transformation.

  Specified by:
    `setParameter` in class `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 `Transformer`

### getParameter

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

  Get a parameter to the transformation

  Specified by:
    `getParameter` in class `Transformer`
  Parameters:
    `expandedName` - of `Object` to get
  Returns:
    A parameter that has been set with setParameter.

### setURIResolver

    public void setURIResolver(URIResolver resolver)

  Set an object that will be used to resolve URIs used in document(), etc.

  Specified by:
    `setURIResolver` in class `Transformer`
  Parameters:
    `resolver` - An object that implements the URIResolver interface, or null.