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

Controller processes an XML file, calling registered node handlers when appropriate to process its elements, character content, and attributes. This is Saxon's implementation of the JAXP Transformer class

Constructor Summary
`Controller(Configuration config)` 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)`
`Bindery` `getBindery()` Get the current bindery.
`Configuration` `getConfiguration()`
`DateTimeValue` `getCurrentDateTime()` Get the current date and time for this query or transformation.
`DecimalFormatManager` `getDecimalFormatManager()` Get the Decimal Format Manager.
`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
`java.lang.String` `getPrincipalResultURI()` Get the URI of 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 primary URI resolver.
`java.lang.Object` `getUserData(java.lang.Object node, java.lang.String name)` Get user data associated with a node.
`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(Builder 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 next invocation of the render method will not send trace events to the listener.
`void` `setBaseOutputURI(java.lang.String uri)` Set the base output URI (as it is known in the XSLT spec).
`void` `setCurrentDateTime(DateTimeValue dateTime)` Set the current date and time for this query or transformation.
`void` `setDecimalFormatManager(DecimalFormatManager manager)` Set the Decimal Format Manager.
`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` `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` `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 node, java.lang.String name, java.lang.Object data)` Set user data associated with a node (or any other object).
`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)` Render 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

Method Detail

### getConfiguration

    public Configuration getConfiguration()

### setInitialMode

    public void setInitialMode(java.lang.String expandedModeName)

  Set the initial mode for the transformation.

  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

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

  Parameters:
    `properties` - the output properties to be used for the transformation

### getOutputProperties

    public java.util.Properties getOutputProperties()

  Get the output properties for the transformation.

  Returns:
    the output properties being used for the transformation, including properties defined in the stylesheet for the unnamed output format

### setOutputProperty

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

  Set an output property for the transformation.

  Parameters:
    `name` - the name of the property
    `value` - the value of the property

### getOutputProperty

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

  Get the value of an output property.

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

### setBaseOutputURI

    public void setBaseOutputURI(java.lang.String uri)

  Set the base output URI (as it is known in the XSLT spec). 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.

### getPrincipalResultURI

    public java.lang.String getPrincipalResultURI()

  Get the URI of the principal result destination.

  Returns:
    the URI, as a String

### getPrincipalResult

    public javax.xml.transform.Result getPrincipalResult()

  Get the principal result destination

### checkUniqueOutputDestination

    public boolean checkUniqueOutputDestination(java.lang.String uri)

  Check that an output destination has not been used before

### setInitialTemplate

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

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

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

### makePipelineConfiguration

    public PipelineConfiguration makePipelineConfiguration()

  Make a PipelineConfiguration based on the properties of this Controller

### makeMessageEmitter

    public Emitter makeMessageEmitter()
                               throws XPathException

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

  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

### getMessageEmitter

    public Emitter getMessageEmitter()

  Get the Emitter used for xsl:message output.

  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.

  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.

  Returns:
    the current policy, as set by setRecoveryPolicy

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

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

### getExecutable

    public Executable getExecutable()

  Get the Executable object.

  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

  Returns:
    the source document pool

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

  Parameters:
    `onOrOff` - true to switch line numbering on; false to switch it off

### setPrincipalSourceDocument

    public void setPrincipalSourceDocument(DocumentInfo doc)

  Set the principal source document (used for evaluating global variables)

### getBindery

    public Bindery getBindery()

  Get the current bindery.

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

### getPrincipalSourceDocument

    public DocumentInfo getPrincipalSourceDocument()

  Get the principal source document

### 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 primary URI resolver.

  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

### setOutputURIResolver

    public void setOutputURIResolver(OutputURIResolver resolver)

  Set the URI resolver for secondary output documents.

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

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

### getKeyManager

    public KeyManager getKeyManager()

  Get the KeyManager.

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

### getNamePool

    public NamePool getNamePool()

  Get the name pool in use.

  Returns:
    the name pool in use

### setTreeModel

    public void setTreeModel(int model)

  Set the tree data model to use.

  Parameters:
    `model` - the required tree model: Builder.STANDARD_TREE or Builder.TINY_TREE
  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

### makeStripper

    public Stripper makeStripper(Builder b)

  Make a Stripper configured to implement the whitespace stripping rules.

  Parameters:
    `b` - the Builder to which the events filtered by this stripper are to be sent. May be null if the stripper is not being used for filtering into a Builder.
  Returns:
    the required stripper

### registerDocument

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

  Add a document to the document pool.

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

### setDecimalFormatManager

    public void setDecimalFormatManager(DecimalFormatManager manager)

  Set the Decimal Format Manager.

  Parameters:
    `manager` - the Decimal Format Manager. This object is responsible for maintaining all named and unnamed decimal format declarations

### getDecimalFormatManager

    public DecimalFormatManager getDecimalFormatManager()

  Get the Decimal Format Manager.

  Returns:
    the Decimal Format Manager

### setRuleManager

    public void setRuleManager(RuleManager r)

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

  Parameters:
    `r` - the Rule Manager

### getRuleManager

    public RuleManager getRuleManager()

  Get the Rule Manager.

  Returns:
    the Rule Manager, used to hold details of template rules for all modes

### getTraceListener

    public TraceListener getTraceListener()

  Get the TraceListener.

  Returns:
    the TraceListener used for XSLT instruction tracing

### isTracing

    public final boolean isTracing()

  Test whether instruction execution is being traced.

  Returns:
    true if tracing is active, false otherwise

### pauseTracing

    public final void pauseTracing(boolean pause)

  Pause or resume tracing.

  Parameters:
    `pause` - true if tracing is to pause; false if it is to resume

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

### setPreparedStylesheet

    public void setPreparedStylesheet(PreparedStylesheet sheet)

  Associate this Controller with a compiled stylesheet.

  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.

### defineGlobalParameters

    public void defineGlobalParameters(Bindery bindery)

### getUserData

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

  Get user data associated with a node.

  Parameters:
    `node` - the node to which the data is attached
    `name` - the name of the required property
  Returns:
    the value of the required property

### setUserData

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

  Set user data associated with a node (or any other object).

  Parameters:
    `node` -
    `name` -
    `data` -

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

  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

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

  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.

  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.

  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.

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

  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.

  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.

  Returns:
    the new XPathContext

### setRememberedNumber

    public void setRememberedNumber(NodeInfo node,
                                    int number)

  Set the last remembered node, for node numbering purposes.

  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.

  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

  Specified by:
    `getInstructionInfo` in interface `InstructionInfoProvider`