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

RECOVER_WITH_WARNINGS

public static final int RECOVER_WITH_WARNINGS

DO_NOT_RECOVER

public static final int DO_NOT_RECOVER
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

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.


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.

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

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.
Overrides:
setOutputProperties in class javax.xml.transform.Transformer

getOutputProperties

public java.util.Properties getOutputProperties()
Get the output properties for the transformation.
Overrides:
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.
Overrides:
setOutputProperty in class javax.xml.transform.Transformer

getOutputProperty

public java.lang.String getOutputProperty(java.lang.String name)
Get the value of an output property
Overrides:
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:
outputProperties - Details of the new output format
result - Details of the new output destination

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

makeMessageEmitter

public Emitter makeMessageEmitter()
                           throws javax.xml.transform.TransformerException
Make an Emitter to be used for xsl:message output

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
Overrides:
setErrorListener in class javax.xml.transform.Transformer

getErrorListener

public javax.xml.transform.ErrorListener getErrorListener()
Get the error listener
Overrides:
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.
Overrides:
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

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:
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.
userData - 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.
Overrides:
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

setParameter

public void setParameter(java.lang.String expandedName,
                         java.lang.Object value)
Set a parameter for the transformation.
Overrides:
setParameter in class javax.xml.transform.Transformer
Parameters:
name - The name of the parameter in {uri}local format

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.
Overrides:
clearParameters in class javax.xml.transform.Transformer

getParameter

public java.lang.Object getParameter(java.lang.String expandedName)
Get a parameter to the transformation
Overrides:
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.
Overrides:
setURIResolver in class javax.xml.transform.Transformer
Parameters:
resolver - An object that implements the URIResolver interface, or null.