Class Controller
- java.lang.Object
-
- javax.xml.transform.Transformer
-
- com.icl.saxon.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
-
-
Field Summary
Fields Modifier and Type Field Description static int
DO_NOT_RECOVER
static int
RECOVER_SILENTLY
static int
RECOVER_WITH_WARNINGS
-
Constructor Summary
Constructors Modifier Constructor Description Controller()
Default constructor is provided for Java-only programs, i.e.protected
Controller(TransformerFactoryImpl factory)
Create a Controller and initialise variables.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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 templatevoid
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 ordervoid
disableWhitespaceStripping(boolean disable)
Disable whitespace strippingBindery
getBindery()
Get the current binderyDecimalFormatManager
getDecimalFormatManager()
DocumentPool
getDocumentPool()
Get the document pool.javax.xml.transform.ErrorListener
getErrorListener()
Get the error listenerKeyManager
getKeyManager()
Get the KeyManagerEmitter
getMessageEmitter()
Get the Emitter used for xsl:message outputNamePool
getNamePool()
Get the name pool in usejava.util.Properties
getOutputProperties()
Get the output properties for the transformation.java.lang.String
getOutputProperty(java.lang.String name)
Get the value of an output propertyOutputter
getOutputter()
Get the current outputterjava.lang.Object
getParameter(java.lang.String expandedName)
Get a parameter to the transformationint
getRecoveryPolicy()
Get the policy for handling recoverable errorsRuleManager
getRuleManager()
javax.xml.transform.URIResolver
getStandardURIResolver()
Get the fallback URI resolver.TraceListener
getTraceListener()
TransformerFactoryImpl
getTransformerFactory()
int
getTreeModel()
Get the tree model in usejavax.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 nodeboolean
isLineNumbering()
Determine whether line numbering is enabledboolean
isTracing()
boolean
isWhitespaceStrippingDisabled()
Determine if whitespace stripping is disabledBuilder
makeBuilder()
Make a builder for the selected tree modelContext
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 outputStripper
makeStripper(Builder b)
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 errorvoid
reportRecoverableError(javax.xml.transform.TransformerException err)
Report a recoverable errorvoid
reset()
Reset thisTransformer
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(javax.xml.transform.ErrorListener listener)
Set the error listenervoid
setLineNumbering(boolean onOrOff)
Set line numbering (of the source document) on or offvoid
setMessageEmitter(Emitter emitter)
Set the Emitter to be used for xsl:message outputvoid
setNamePool(NamePool pool)
Set the name pool to be usedvoid
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 stylesheetvoid
setRecoveryPolicy(int policy)
Set the policy for handling recoverable errorsvoid
setRuleManager(RuleManager r)
void
setTraceListener(TraceListener trace)
void
setTreeModel(int model)
Set the tree data model to usevoid
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?
-
-
-
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 withTransformerFactory.newTransformer()
,TransformerFactory.newTransformer(javax.xml.transform.Source source)
orTemplates.newTransformer()
.reset()
is designed to allow the reuse of existingTransformer
s thus saving resources associated with the creation of newTransformer
s.The reset
Transformer
is not guaranteed to have the sameURIResolver
orErrorListener
Object
s, e.g.Object.equals(Object obj)
. It is guaranteed to have a functionally equalURIResolver
andErrorListener
.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 classjavax.xml.transform.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()
- Overrides:
toString
in classjava.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 interfaceNodeOrderComparer
- Parameters:
n1
- The first noden2
- 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 classjavax.xml.transform.Transformer
-
getOutputProperties
public java.util.Properties getOutputProperties()
Get the output properties for the transformation.- Specified by:
getOutputProperties
in classjavax.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 classjavax.xml.transform.Transformer
-
getOutputProperty
public java.lang.String getOutputProperty(java.lang.String name)
Get the value of an output property- Specified by:
getOutputProperty
in classjavax.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 formatresult
- 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 classjavax.xml.transform.Transformer
-
getErrorListener
public javax.xml.transform.ErrorListener getErrorListener()
Get the error listener- Specified by:
getErrorListener
in classjavax.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 classjavax.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:
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 classjavax.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 startresult
- 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 classjavax.xml.transform.Transformer
- Parameters:
expandedName
- The name of the parameter in {uri}local formatvalue
- 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 classjavax.xml.transform.Transformer
-
getParameter
public java.lang.Object getParameter(java.lang.String expandedName)
Get a parameter to the transformation- Specified by:
getParameter
in classjavax.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 classjavax.xml.transform.Transformer
- Parameters:
resolver
- An object that implements the URIResolver interface, or null.
-
-