com.icl.saxon

Class Controller

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.

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

Field Summary
static intDO_NOT_RECOVER
static intRECOVER_SILENTLY
static intRECOVER_WITH_WARNINGS
Constructor Summary
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
protected Controller(TransformerFactoryImpl factory)
Create a Controller and initialise variables.
Method Summary
voidaddTraceListener(TraceListener trace)
Adds the specified trace listener to receive trace events from this instance.
voidapplyImports(Context c, Mode mode, int min, int max, ParameterSet params)
Apply a template imported from the stylesheet containing the current template
voidapplyTemplates(Context c, Expression select, Mode mode, ParameterSet parameters)
ApplyTemplates to process selected nodes using the handlers registered for a particular mode.
voidchangeOutputDestination(Properties props, Result result)
Set a new output destination, supplying the output format details.
voidchangeToTextOutputDestination(StringBuffer buffer)
Set a simple StringBuffer output destination.
voidclearDocumentPool()
Clear the document pool.
voidclearParameters()
Reset the parameters to a null list.
intcompare(NodeInfo n1, NodeInfo n2)
Compare the position of two nodes in document order
voiddisableWhitespaceStripping(boolean disable)
Disable whitespace stripping
BinderygetBindery()
Get the current bindery
DecimalFormatManagergetDecimalFormatManager()
DocumentPoolgetDocumentPool()
Get the document pool.
ErrorListenergetErrorListener()
Get the error listener
KeyManagergetKeyManager()
Get the KeyManager
EmittergetMessageEmitter()
Get the Emitter used for xsl:message output
NamePoolgetNamePool()
Get the name pool in use
PropertiesgetOutputProperties()
Get the output properties for the transformation.
StringgetOutputProperty(String name)
Get the value of an output property
OutputtergetOutputter()
Get the current outputter
ObjectgetParameter(String expandedName)
Get a parameter to the transformation
intgetRecoveryPolicy()
Get the policy for handling recoverable errors
RuleManagergetRuleManager()
URIResolvergetStandardURIResolver()
Get the fallback URI resolver.
TraceListenergetTraceListener()
TransformerFactoryImplgetTransformerFactory()
intgetTreeModel()
Get the tree model in use
URIResolvergetURIResolver()
Get the primary URI resolver.
ObjectgetUserData(NodeInfo node, String name)
Get the named user data property for the node
booleanisLineNumbering()
Determine whether line numbering is enabled
booleanisTracing()
booleanisWhitespaceStrippingDisabled()
Determine if whitespace stripping is disabled
BuildermakeBuilder()
Make a builder for the selected tree model
ContextmakeContext(NodeInfo node)
Create a new context with a given node as the current node and the only node in the current node list.
EmittermakeMessageEmitter()
Make an Emitter to be used for xsl:message output
StrippermakeStripper(Builder b)
voidpauseTracing(boolean pause)
voidremoveTraceListener(TraceListener trace)
Removes the specified trace listener so that the next invocation of the render method will not send trace events to the listener.
voidreportRecoverableError(String message, SourceLocator location)
Report a recoverable error
voidreportRecoverableError(TransformerException err)
Report a recoverable error
voidreset()

Reset this Transformer to its original configuration.

Transformer is reset to the same state as when it was created with javax.xml.transform.TransformerFactory#newTransformer(), javax.xml.transform.TransformerFactory#newTransformer(javax.xml.transform.Source source) or javax.xml.transform.Templates#newTransformer().

voidresetOutputDestination(Outputter outputter)
Close the current outputter, and revert to the previous outputter.
voidrun(NodeInfo node)
Process a Document.

This method is intended for use when performing a pure Java transformation, without a stylesheet.

voidsetDecimalFormatManager(DecimalFormatManager manager)
voidsetDiagnosticName(String name)
Set a diagnostic name for this transformation (accessible through toString())
voidsetErrorListener(ErrorListener listener)
Set the error listener
voidsetLineNumbering(boolean onOrOff)
Set line numbering (of the source document) on or off
voidsetMessageEmitter(Emitter emitter)
Set the Emitter to be used for xsl:message output
voidsetNamePool(NamePool pool)
Set the name pool to be used
voidsetOutputProperties(Properties properties)
Set the output properties for the transformation.
voidsetOutputProperty(String name, String value)
Set an output property for the transformation.
voidsetParameter(String expandedName, Object value)
Set a parameter for the transformation.
voidsetParams(ParameterSet params)
Set parameters supplied externally (typically, on the command line). (non-TRAX method retained for backwards compatibility)
voidsetPreparedStyleSheet(PreparedStyleSheet sheet)
Associate this Controller with a compiled stylesheet
voidsetRecoveryPolicy(int policy)
Set the policy for handling recoverable errors
voidsetRuleManager(RuleManager r)
voidsetTraceListener(TraceListener trace)
voidsetTreeModel(int model)
Set the tree data model to use
voidsetURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in document(), etc.
voidsetUserData(NodeInfo node, String name, Object data)
Set a user data property for a node.
StringtoString()
voidtransform(Source source, Result result)
Process the source tree to SAX parse events.
voidtransformDocument(NodeInfo startNode, Result result)
Render a source XML document supplied as a tree.
protected booleanusesPreviewMode()
Does this transformation use preview mode?

Field Detail

DO_NOT_RECOVER

public static final int DO_NOT_RECOVER

RECOVER_SILENTLY

public static final int RECOVER_SILENTLY

RECOVER_WITH_WARNINGS

public static final int RECOVER_WITH_WARNINGS

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

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.

applyImports

public void applyImports(Context c, Mode mode, int min, int max, ParameterSet params)
Apply a template imported from the stylesheet containing the current template

applyTemplates

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

changeOutputDestination

public void changeOutputDestination(Properties props, Result result)
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

changeToTextOutputDestination

public void changeToTextOutputDestination(StringBuffer buffer)
Set a simple StringBuffer output destination. Used during calls to xsl:attribute, xsl:comment, xsl:processing-instruction

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.

clearParameters

public void clearParameters()
Reset the parameters to a null list.

compare

public int compare(NodeInfo n1, NodeInfo n2)
Compare the position of two nodes in document order

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

disableWhitespaceStripping

public void disableWhitespaceStripping(boolean disable)
Disable whitespace stripping

getBindery

public Bindery getBindery()
Get the current bindery

getDecimalFormatManager

public DecimalFormatManager getDecimalFormatManager()

getDocumentPool

public DocumentPool getDocumentPool()
Get the document pool. This is used only for source documents, not for stylesheet modules

getErrorListener

public ErrorListener getErrorListener()
Get the error listener

getKeyManager

public KeyManager getKeyManager()
Get the KeyManager

getMessageEmitter

public Emitter getMessageEmitter()
Get the Emitter used for xsl:message output

getNamePool

public NamePool getNamePool()
Get the name pool in use

getOutputProperties

public Properties getOutputProperties()
Get the output properties for the transformation.

getOutputProperty

public String getOutputProperty(String name)
Get the value of an output property

getOutputter

public Outputter getOutputter()
Get the current outputter

getParameter

public Object getParameter(String expandedName)
Get a parameter to the transformation

getRecoveryPolicy

public int getRecoveryPolicy()
Get the policy for handling recoverable errors

getRuleManager

public RuleManager getRuleManager()

getStandardURIResolver

public URIResolver getStandardURIResolver()
Get the fallback URI resolver.

Returns: the the system-defined URIResolver

getTraceListener

public TraceListener getTraceListener()

getTransformerFactory

public TransformerFactoryImpl getTransformerFactory()

getTreeModel

public int getTreeModel()
Get the tree model in use

getURIResolver

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

getUserData

public Object getUserData(NodeInfo node, 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.

isLineNumbering

public boolean isLineNumbering()
Determine whether line numbering is enabled

isTracing

public final boolean isTracing()

isWhitespaceStrippingDisabled

public boolean isWhitespaceStrippingDisabled()
Determine if whitespace stripping is disabled

makeBuilder

public Builder makeBuilder()
Make a builder for the selected tree model

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.

makeMessageEmitter

public Emitter makeMessageEmitter()
Make an Emitter to be used for xsl:message output

makeStripper

public Stripper makeStripper(Builder b)

pauseTracing

public void pauseTracing(boolean pause)

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.

reportRecoverableError

public void reportRecoverableError(String message, SourceLocator location)
Report a recoverable error

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

reportRecoverableError

public void reportRecoverableError(TransformerException err)
Report a recoverable error

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

reset

public void reset()

Reset this Transformer to its original configuration.

Transformer is reset to the same state as when it was created with javax.xml.transform.TransformerFactory#newTransformer(), javax.xml.transform.TransformerFactory#newTransformer(javax.xml.transform.Source source) or javax.xml.transform.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 javax.xml.transform.URIResolver or javax.xml.transform.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.

Since: 1.5

resetOutputDestination

public void resetOutputDestination(Outputter outputter)
Close the current outputter, and revert to the previous outputter.

Parameters: outputter The outputter to revert to

run

public void run(NodeInfo node)
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.

setDecimalFormatManager

public void setDecimalFormatManager(DecimalFormatManager manager)

setDiagnosticName

public void setDiagnosticName(String name)
Set a diagnostic name for this transformation (accessible through toString())

setErrorListener

public void setErrorListener(ErrorListener listener)
Set the error listener

setLineNumbering

public void setLineNumbering(boolean onOrOff)
Set line numbering (of the source document) on or off

setMessageEmitter

public void setMessageEmitter(Emitter emitter)
Set the Emitter to be used for xsl:message output

setNamePool

public void setNamePool(NamePool pool)
Set the name pool to be used

setOutputProperties

public void setOutputProperties(Properties properties)
Set the output properties for the transformation. These properties will override properties set in the templates with xsl:output.

setOutputProperty

public void setOutputProperty(String name, String value)
Set an output property for the transformation.

setParameter

public void setParameter(String expandedName, 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.

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.

setPreparedStyleSheet

public void setPreparedStyleSheet(PreparedStyleSheet sheet)
Associate this Controller with a compiled stylesheet

setRecoveryPolicy

public void setRecoveryPolicy(int policy)
Set the policy for handling recoverable errors

setRuleManager

public void setRuleManager(RuleManager r)

setTraceListener

public void setTraceListener(TraceListener trace)

setTreeModel

public void setTreeModel(int model)
Set the tree data model to use

setURIResolver

public void setURIResolver(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.

setUserData

public void setUserData(NodeInfo node, String name, 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().

toString

public String toString()

transform

public void transform(Source source, Result result)
Process the source tree to SAX parse events.

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

usesPreviewMode

protected boolean usesPreviewMode()
Does this transformation use preview mode?