Package com.icl.saxon

Class Controller

  • All Implemented Interfaces:
    NodeOrderComparer
    Direct Known Subclasses:
    IdentityTransformer

    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.

    Version:
    10 December 1999: methods for building the tree extracted to class Builder, methods for maintaining rulesets extracted to RuleManager.

    The Controller class now incorporates the previous StylesheetInstance class. A StyleSheetInstance represents a single execution of a prepared stylesheet. A PreparedStyleSheet can be used any number of times, in series or in parallel, but each use of it to render a source document requires a separate Controller object, which is not reusable or shareable.

    The Controller is capable of comparing whether nodes are in document order; therefore it acts as a NodeOrderComparer.

    Author:
    Michael H. Kay
    • 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 Transformers thus saving resources associated with the creation of new Transformers.

        The reset Transformer is not guaranteed to have the same URIResolver or ErrorListener Objects, 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
      • 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
      • setRuleManager

        public void setRuleManager​(RuleManager r)
      • setTraceListener

        public void setTraceListener​(TraceListener trace)
      • 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.