net.sf.saxon

Class Controller

Implemented Interfaces:
InstructionInfoProvider

public class Controller
extends Transformer
implements InstructionInfoProvider

The Controller is Saxon's implementation of the JAXP Transformer class, and represents an executing instance of a transformation or query. Multiple concurrent executions of the same transformation or query will use different Controller instances. This class is therefore not thread-safe.

The Controller is serially reusable, as required by JAXP: when one transformation or query is finished, it can be used to run another. However, there is no advantage in doing this rather than allocating a new Controller each time.

The Controller can also be used when running Java applications that use neither XSLT nor XQuery. A dummy Controller is created when running free-standing XPath expressions.

The Controller holds those parts of the dynamic context that do not vary during the course of a transformation or query, or that do not change once their value has been computed. This also includes those parts of the static context that are required at run-time.

Wherever possible XSLT applications should use the JAXP Transformer class directly, rather than relying on Saxon-specific methods in the Controller. However, some features are currently available only through this class. This applies especially to new features specific to XSLT 2.0, since the JAXP interface still supports only XSLT 1.0. Such methods may be superseded in the future by JAXP methods.

Many methods on the Controller are designed for internal use and should not be considered stable. From release 8.4 onwards, those methods that are considered sufficiently stable to constitute path of the Saxon public API are labelled with the JavaDoc tag "since": the value indicates the release at which the method was added to the public API.

Author:
Michael H. Kay
Since:
8.4

Constructor Summary

Controller(Configuration config)
Create a Controller and initialise variables.
Controller(Configuration config, Executable executable)
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
addUnavailableOutputDestination(String uri)
Add a URI to the set of output destinations that cannot be written to, either because they have already been written to, or because they have been read
void
allocateGlobalVariables(int numberOfVariables)
Allocate space in the bindery for global variables.
SequenceOutputter
allocateSequenceOutputter(int size)
Allocate a SequenceOutputter for a new output destination.
void
checkImplicitResultTree()
Check whether an XSLT implicit result tree can be written.
boolean
checkUniqueOutputDestination(String uri)
Check that an output destination has not been used before, optionally adding this URI to the set of URIs that have been used.
void
clearDocumentPool()
Clear the document pool.
void
clearParameters()
Reset the parameters to a null list.
void
defineGlobalParameters()
Register the global parameters of the transformation or query.
String
getBaseOutputURI()
Get the base output URI.
Bindery
getBindery()
Get the current bindery.
ClassLoader
getClassLoader()
Get the ClassLoader supplied using the method setClassLoader(ClassLoader).
Configuration
getConfiguration()
Get the Configuration associated with this Controller.
Item
getContextForGlobalVariables()
Get the item used as the context for evaluating global variables.
DateTimeValue
getCurrentDateTime()
Get the current date and time for this query or transformation.
DocumentPool
getDocumentPool()
Get the document pool.
ErrorListener
getErrorListener()
Get the error listener.
Executable
getExecutable()
Get the Executable object.
int
getImplicitTimezone()
Get the implicit timezone for this query or transformation
Item
getInitialContextItem()
Get the initial context item.
String
getInitialMode()
Get the initial mode for the transformation
String
getInitialTemplate()
Get the initial template
InstructionInfo
getInstructionInfo()
Get diagnostic information about this context.
KeyManager
getKeyManager()
Get the KeyManager.
Receiver
getMessageEmitter()
Get the Emitter used for xsl:message output.
NamePool
getNamePool()
Get the name pool in use.
Properties
getOutputProperties()
Get the output properties for the transformation.
String
getOutputProperty(String name)
Get the value of an output property.
OutputURIResolver
getOutputURIResolver()
Get the output URI resolver.
Object
getParameter(String expandedName)
Get a parameter to the transformation.
PathMap
getPathMapForDocumentProjection()
Get the path map used for document projection, if any.
Result
getPrincipalResult()
Get the principal result destination.
DocumentInfo
getPrincipalSourceDocument()
Deprecated. From Saxon 8.7, replaced by getInitialContextItem() and getContextForGlobalVariables()
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.
SchemaURIResolver
getSchemaURIResolver()
Get the SchemaURIResolver used for resolving references to schema documents.
URIResolver
getStandardURIResolver()
Get the fallback URI resolver.
TraceListener
getTraceListener()
Get the TraceListener.
URIResolver
getURIResolver()
Get the URI resolver.
UnparsedTextURIResolver
getUnparsedTextURIResolver()
Get the URI resolver for the unparsed-text() function.
Object
getUserData(Object key, String name)
Get user data associated with a key.
boolean
hasThereBeenAnExplicitResultDocument()
Test whether an explicit result tree has been written using xsl:result-document
void
initializeController()
Initialize the controller ready for a new transformation.
boolean
isTracing()
Test whether instruction execution is being traced.
boolean
isUnusedOutputDestination(String uri)
Determine whether an output URI is available for use.
Iterator
iterateParameters()
Get an iterator over the names of global parameters that have been defined
Builder
makeBuilder()
Make a builder for the selected tree model.
CharacterMapExpander
makeCharacterMapExpander(String useMaps, SerializerFactory sf)
Make a CharacterMapExpander to handle the character map definitions in the serialization properties.
PipelineConfiguration
makePipelineConfiguration()
Make a PipelineConfiguration based on the properties of this Controller.
Stripper
makeStripper(Receiver 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(Source source)
Prepare an input tree for processing.
Result
prepareNextStylesheet(String href, String baseURI, Result result)
Prepare another stylesheet to handle the output of this one.
void
recoverableError(XPathException err)
Report a recoverable error.
void
registerDocument(DocumentInfo doc, String systemId)
Add a document to the document pool.
void
removeTraceListener(TraceListener trace)
Removes the specified trace listener so that the listener will no longer receive trace events.
void
removeUnavailableOutputDestination(String uri)
Remove a URI from the set of output destinations that cannot be written to or read from.
void
reportFatalError(XPathException err)
Report a fatal error
void
reset()
Reset this Transformer to its original configuration.
void
reuseSequenceOutputter(SequenceOutputter out)
Accept a SequenceOutputter that is now available for reuse
void
setBaseOutputURI(String uri)
Set the base output URI.
void
setClassLoader(ClassLoader loader)
Set a ClassLoader to be used when loading external classes.
void
setCurrentDateTime(DateTimeValue dateTime)
Set the current date and time for this query or transformation.
void
setErrorListener(ErrorListener listener)
Set the error listener.
void
setExecutable(Executable exec)
Associate this Controller with an Executable.
void
setInitialContextItem(Item item)
Set the initial context item.
void
setInitialMode(String expandedModeName)
Set the initial mode for the transformation.
void
setInitialTemplate(String expandedName)
Set the initial named template to be used as the entry point.
void
setMessageEmitter(Receiver receiver)
Set the Receiver to be used for xsl:message output.
void
setOutputProperties(Properties properties)
Set the output properties for the transformation.
void
setOutputProperty(String name, String value)
Set an output property for the transformation.
void
setOutputURIResolver(OutputURIResolver resolver)
Set the URI resolver for secondary output documents.
void
setParameter(String expandedName, Object value)
Set a parameter for the transformation.
void
setParameter(StructuredQName qName, ValueRepresentation value)
Supply a parameter using Saxon-specific representations of the name and value
void
setPreparedStylesheet(PreparedStylesheet sheet)
Associate this Controller with a compiled stylesheet.
void
setPrincipalSourceDocument(DocumentInfo doc)
Deprecated. From Saxon 8.7, replaced by setInitialContextItem(Item)
void
setRecoveryPolicy(int policy)
Set the policy for handling recoverable errrors
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
setSchemaURIResolver(SchemaURIResolver resolver)
Set the SchemaURIResolver used for resolving references to schema documents.
void
setThereHasBeenAnExplicitResultDocument()
Set that an explicit result tree has been written using xsl:result-document
void
setTreeModel(int model)
Set the tree data model to use.
void
setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in document(), etc.
void
setUnparsedTextURIResolver(UnparsedTextURIResolver resolver)
Set an UnparsedTextURIResolver to be used to resolve URIs passed to the XSLT unparsed-text() function.
void
setUseDocumentProjection(PathMap pathMap)
Indicate whether document projection should be used, and supply the PathMap used to control it.
void
setUserData(Object key, String name, Object data)
Set user data associated with a key.
void
transform(Source source, Result result)
Perform a transformation from a Source document to a Result document.
void
transformDocument(NodeInfo startNode, Result result)
Transform a source XML document supplied as a tree.
static NodeInfo
unravel(Source source, Configuration config)
Deprecated. since 9.0: use Configuration.unravel(Source)

Constructor Details

Controller

public Controller(Configuration config)
Create a Controller and initialise variables. Note: XSLT applications should create the Controller by using the JAXP newTransformer() method.
Parameters:
config - The Configuration used by this Controller

Controller

public Controller(Configuration config,
                  Executable executable)
Create a Controller and initialise variables.
Parameters:
config - The Configuration used by this Controller
executable - The executable used by this Controller

Method Details

addTraceListener

public void addTraceListener(TraceListener trace)
Adds the specified trace listener to receive trace events from this instance. Note that although TraceListeners can be added or removed dynamically, this has no effect unless the stylesheet or query has been compiled with tracing enabled. This is achieved by calling Configuration.setTraceListener(TraceListener) or by setting the attribute FeatureKeys.TRACE_LISTENER on the TransformerFactory. Conversely, if this property has been set in the Configuration or TransformerFactory, the TraceListener will automatically be added to every Controller that uses that Configuration.
Parameters:
trace - the trace listener. If null is supplied, the call has no effect.
Since:
8.4

addUnavailableOutputDestination

public void addUnavailableOutputDestination(String uri)
Add a URI to the set of output destinations that cannot be written to, either because they have already been written to, or because they have been read
Parameters:
uri - A URI that is not available as an output destination

allocateGlobalVariables

public void allocateGlobalVariables(int numberOfVariables)
Allocate space in the bindery for global variables.

For internal use only.

Parameters:
numberOfVariables - the number of global variables for which space is required

allocateSequenceOutputter

public SequenceOutputter allocateSequenceOutputter(int size)
Allocate a SequenceOutputter for a new output destination. Reuse the existing one if it is available for reuse (this is designed to ensure that the TinyTree structure is also reused, creating a forest of trees all sharing the same data structure)
Parameters:
size - the estimated size of the output sequence
Returns:
SequenceOutputter the allocated SequenceOutputter

checkImplicitResultTree

public void checkImplicitResultTree()
            throws XPathException
Check whether an XSLT implicit result tree can be written. This is allowed only if no xsl:result-document has been written for the principal output URI

checkUniqueOutputDestination

public boolean checkUniqueOutputDestination(String uri)
Check that an output destination has not been used before, optionally adding this URI to the set of URIs that have been used.
Parameters:
uri - the URI to be used as the output destination
Returns:
true if the URI is available for use; false if it has already been used.

This method is intended for internal use only.


clearDocumentPool

public void clearDocumentPool()
Clear the document pool. This is sometimes useful when re-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.

defineGlobalParameters

public void defineGlobalParameters()
            throws XPathException
Register the global parameters of the transformation or query. This should be called after a sequence of calls on setParameter. It checks that all required parameters have been supplied, and places the values of the parameters in the Bindery to make them available for use during the query or transformation.

This method is intended for internal use only


getBaseOutputURI

public String getBaseOutputURI()
Get the base output URI. 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.

The concept of the base output URI is new in XSLT 2.0: it defines the base URI for resolving relative URIs in the href attribute of the xsl:result-document instruction. This method may be superseded by a standard JAXP method when JAXP is updated to support XSLT 2.0.

Returns:
the base output URI
Since:
8.4

getBindery

public Bindery getBindery()
Get the current bindery.

This method is intended for internal use only.

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

getClassLoader

public ClassLoader getClassLoader()
Get the ClassLoader supplied using the method setClassLoader(ClassLoader). If none has been supplied, return null.

This method is for application use, but is experimental and subject to change.

Returns:
the ClassLoader in use.

getConfiguration

public Configuration getConfiguration()
Get the Configuration associated with this Controller. The Configuration holds settings that potentially apply globally to many different queries and transformations.
Returns:
the Configuration object
Since:
8.4

getContextForGlobalVariables

public Item getContextForGlobalVariables()
Get the item used as the context for evaluating global variables. In XQuery this is the same as the initial context item; in XSLT it is the root of the tree containing the initial context node.
Returns:
the context item for evaluating global variables, or null if there is none
Since:
8.7

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

getDocumentPool

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

This method is intended for internal use only.

Returns:
the source document pool

getErrorListener

public ErrorListener getErrorListener()
Get the error listener.
Returns:
the ErrorListener in use

getExecutable

public Executable getExecutable()
Get the Executable object.

This method is intended for internal use only.

Returns:
the Executable (which represents the compiled stylesheet)

getImplicitTimezone

public int getImplicitTimezone()
Get the implicit timezone for this query or transformation
Returns:
the implicit timezone as an offset in minutes

getInitialContextItem

public Item getInitialContextItem()
Get the initial context item. This returns the item (often a document node) previously supplied to the setInitialContextItem(Item) method, or the initial context node set implicitly using methods such as transform(Source,Result).
Returns:
the initial context item. Note that in XSLT this must be a node, but in XQuery it may also be an atomic value.
Since:
8.7

getInitialMode

public String getInitialMode()
Get the initial mode for the transformation
Returns:
the initial mode, as a name in Clark format

getInitialTemplate

public String getInitialTemplate()
Get the initial template
Returns:
the name of the initial template, as an expanded name in Clark format if set, or null otherwise
Since:
8.7

getInstructionInfo

public InstructionInfo getInstructionInfo()
Get diagnostic information about this context.

This method is intended for internal use.

Specified by:
getInstructionInfo in interface InstructionInfoProvider

getKeyManager

public KeyManager getKeyManager()
Get the KeyManager.

This method is intended for internal use only.

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

getMessageEmitter

public Receiver getMessageEmitter()
Get the Emitter used for xsl:message output. This returns the emitter previously supplied to the setMessageEmitter(Receiver) method, or the default message emitter otherwise.
Returns:
the Receiver being used for xsl:message output
Since:
8.4; changed in 8.9 to return a Receiver rather than an Emitter

getNamePool

public NamePool getNamePool()
Get the name pool in use. The name pool is responsible for mapping QNames used in source documents and compiled stylesheets and queries into numeric codes. All source documents used by a given transformation or query must use the same name pool as the compiled stylesheet or query.
Returns:
the name pool in use
Since:
8.4

getOutputProperties

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

As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in SaxonOutputKeys. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

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

getOutputProperty

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

As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in SaxonOutputKeys. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

Parameters:
name - the name of the requested property
Returns:
the value of the requested property
Since:
8.4

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.
Since:
8.4

getParameter

public Object getParameter(String expandedName)
Get a parameter to the transformation. This returns the value of a parameter that has been previously set using the setParameter method. The value is returned exactly as supplied, that is, before any conversion to an XPath value.
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

getPathMapForDocumentProjection

public PathMap getPathMapForDocumentProjection()
Get the path map used for document projection, if any.
Returns:
the path map to be used for document projection, if one has been supplied; otherwise null

getPrincipalResult

public Result getPrincipalResult()
Get the principal result destination.

This method is intended for internal use only. It is typically called by Saxon during the course of a transformation, to discover the result that was supplied in the transform() call.

Returns:
the Result object supplied as the principal result destination.

getPrincipalSourceDocument

public DocumentInfo getPrincipalSourceDocument()

Deprecated. From Saxon 8.7, replaced by getInitialContextItem() and getContextForGlobalVariables()

Get the context item used for evaluating global variables, provided this is a document node. If the initial context item is not defined, or is not a node in a document, return null.
Returns:
the context item used for evaluating global variables, provided this is a document node, otherwise null
Since:
8.4

getRecoveryPolicy

public int getRecoveryPolicy()
Get the policy for handling recoverable errors
Returns:
the current policy. If none has been set with this Controller, the value registered with the Configuration is returned.
Since:
8.7.1

getRememberedNumber

public int getRememberedNumber(NodeInfo node)
Get the number of a node if it is the last remembered one.

This method is strictly for internal use only.

Parameters:
node - the node for which remembered information is required
Returns:
the number of this node if known, else -1.

getRuleManager

public RuleManager getRuleManager()
Get the Rule Manager.

This method is intended for internal use only.

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

getSchemaURIResolver

public SchemaURIResolver getSchemaURIResolver()
Get the SchemaURIResolver used for resolving references to schema documents. If none has been set on the Controller, returns the SchemaURIResolver registered with the Configuration
Returns:
the resolver for references to schema documents

getStandardURIResolver

public URIResolver getStandardURIResolver()
Get the fallback URI resolver. This is the URIResolver that Saxon uses when the user-supplied URI resolver returns null.

This method is intended for internal use only.

Returns:
the the system-defined URIResolver

getTraceListener

public TraceListener getTraceListener()
Get the TraceListener. By default, there is no TraceListener, and this method returns null. A TraceListener may be added using the method addTraceListener(TraceListener). If more than one TraceListener has been added, this method will return a composite TraceListener. Because this form this takes is implementation-dependent, this method is not part of the stable Saxon public API.
Returns:
the TraceListener used for XSLT or XQuery instruction tracing

getURIResolver

public URIResolver getURIResolver()
Get the URI resolver.

This method changed in Saxon 8.5, to conform to the JAXP specification. If there is no user-specified URIResolver, it now returns null; previously it returned the system default URIResolver.

Returns:
the user-supplied URI resolver if there is one, or null otherwise.

getUnparsedTextURIResolver

public UnparsedTextURIResolver getUnparsedTextURIResolver()
Get the URI resolver for the unparsed-text() function. This will return the UnparsedTextURIResolver previously set using the setUnparsedTextURIResolver(UnparsedTextURIResolver) method.
Returns:
the registered UnparsedTextURIResolver
Since:
8.9

getUserData

public Object getUserData(Object key,
                          String name)
Get user data associated with a key. To retrieve user data, two objects are required: an arbitrary object that may be regarded as the container of the data (originally, and typically still, a node in a tree), and a name. The name serves to distingush data objects associated with the same node by different client applications.

This method is intended primarily for internal use, though it may also be used by advanced applications.

Returns:
the value of the required property

hasThereBeenAnExplicitResultDocument

public boolean hasThereBeenAnExplicitResultDocument()
Test whether an explicit result tree has been written using xsl:result-document
Returns:
true if the transformation has evaluated an xsl:result-document instruction

initializeController

public void initializeController()
            throws XPathException
Initialize the controller ready for a new transformation. This method should not normally be called by users (it is done automatically when transform() is invoked). However, it is available as a low-level API especially for use with XQuery.

isTracing

public final boolean isTracing()
Returns:
true if tracing is active, false otherwise
Since:
8.4

isUnusedOutputDestination

public boolean isUnusedOutputDestination(String uri)
Determine whether an output URI is available for use. This method is intended for use by applications, via an extension function.
Parameters:
uri - A uri that the application is proposing to use in the href attribute of xsl:result-document: if this function returns false, then the xsl:result-document call will fail saying the URI has already been used.
Returns:
true if the URI is available for use. Note that this function is not "stable": it may return different results for the same URI at different points in the transformation.

iterateParameters

public Iterator iterateParameters()
Get an iterator over the names of global parameters that have been defined
Returns:
an Iterator whose items are strings in the form of Clark names, that is {uri}local

makeBuilder

public Builder makeBuilder()
Make a builder for the selected tree model.
Returns:
an instance of the Builder for the chosen tree model
Since:
8.4

makeCharacterMapExpander

public CharacterMapExpander makeCharacterMapExpander(String useMaps,
                                                     SerializerFactory sf)
            throws XPathException
Make a CharacterMapExpander to handle the character map definitions in the serialization properties.

This method is intended for internal use only.

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).
sf - the SerializerFactory - used to create a CharacterMapExpander
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.

makePipelineConfiguration

public PipelineConfiguration makePipelineConfiguration()
Make a PipelineConfiguration based on the properties of this Controller.

This interface is intended primarily for internal use, although it may be necessary for applications to call it directly if they construct pull or push pipelines

Returns:
a newly constructed PipelineConfiguration holding a reference to this Controller as well as other configuration information.

makeStripper

public Stripper makeStripper(Receiver b)
Make a Stripper configured to implement the whitespace stripping rules. In the case of XSLT the whitespace stripping rules are normally defined by xsl:strip-space and xsl:preserve-spaceConfiguration.setStripsAllWhiteSpace(boolean).
Parameters:
b - the Receiver to which the events filtered by this stripper are to be sent (often a Builder). May be null if the stripper is not being used for filtering into a Builder or other Receiver.
Returns:
the required Stripper. A Stripper may be used in two ways. It acts as a filter applied to an event stream, that can be used to remove the events representing whitespace text nodes before they reach a Builder. Alternatively, it can be used to define a view of an existing tree in which the whitespace text nodes are dynamically skipped while navigating the XPath axes.
Since:
8.4 - Generalized in 8.5 to accept any Receiver as an argument

newXPathContext

public XPathContextMajor newXPathContext()
Make an XPathContext object for expression evaluation.

This method is intended for internal use.

Returns:
the new XPathContext

pauseTracing

public final void pauseTracing(boolean pause)
Pause or resume tracing. While tracing is paused, trace events are not sent to any of the registered TraceListeners.
Parameters:
pause - true if tracing is to pause; false if it is to resume
Since:
8.4

preEvaluateGlobals

public void preEvaluateGlobals(XPathContext context)
            throws XPathException
Pre-evaluate global variables (when debugging/tracing).

This method is intended for internal use.

Parameters:
context - the dynamic context for evaluating the global variables
Throws:
XPathException - if a dynamic error occurs while evaluating the global variables.

prepareInputTree

public NodeInfo prepareInputTree(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.

This method is intended for internal use.

Parameters:
source - the input tree. Must be either a DOMSource or a NodeInfo
Returns:
the NodeInfo representing the input node, suitably wrapped.

prepareNextStylesheet

public Result prepareNextStylesheet(String href,
                                    String baseURI,
                                    Result result)
            throws TransformerException
Prepare another stylesheet to handle the output of this one.

This method is intended for internal use, to support the saxon:next-in-chain extension.

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

recoverableError

public void recoverableError(XPathException err)
            throws XPathException
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.

This method is intended for internal use only.

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

registerDocument

public void registerDocument(DocumentInfo doc,
                             String systemId)
Add a document to the document pool.

This method is intended for internal use only.

Parameters:
doc - the root node of the document to be added
systemId - the document-URI property of this document

removeTraceListener

public void removeTraceListener(TraceListener trace)
Removes the specified trace listener so that the listener will no longer receive trace events.
Parameters:
trace - the trace listener.
Since:
8.4

removeUnavailableOutputDestination

public void removeUnavailableOutputDestination(String uri)
Remove a URI from the set of output destinations that cannot be written to or read from. Used to support saxon:discard-document()
Parameters:
uri - A URI that is being made available as an output destination

reportFatalError

public void reportFatalError(XPathException err)
Report a fatal error
Parameters:
err - the error to be reported

reset

public void reset()
Since:
1.5

reuseSequenceOutputter

public void reuseSequenceOutputter(SequenceOutputter out)
Accept a SequenceOutputter that is now available for reuse
Parameters:
out - the SequenceOutputter that is available for reuse

setBaseOutputURI

public void setBaseOutputURI(String uri)
Set the base output URI. 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.

The concept of the base output URI is new in XSLT 2.0: it defines the base URI for resolving relative URIs in the href attribute of the xsl:result-document instruction. This method may be superseded by a standard JAXP method when JAXP is updated to support XSLT 2.0.

Parameters:
uri - the base output URI
Since:
8.4

setClassLoader

public void setClassLoader(ClassLoader loader)
Set a ClassLoader to be used when loading external classes. Examples of classes that are loaded include SAX parsers, localization modules for formatting numbers and dates, extension functions, external object models. In an environment such as Eclipse that uses its own ClassLoader, this ClassLoader should be nominated to ensure that any class loaded by Saxon is identical to a class of the same name loaded by the external environment.

This method is for application use, but is experimental and subject to change.

Parameters:
loader - the ClassLoader to be used.

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.

Note that comparisons of date/time values currently use the implicit timezone taken from the system clock, not from the value supplied here.

Parameters:
dateTime - the date/time value to be used as the current date and time

setErrorListener

public void setErrorListener(ErrorListener listener)
Set the error listener.
Parameters:
listener - the ErrorListener to be used

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.

This method is intended for internal use only

Parameters:
exec - the Executable

setInitialContextItem

public void setInitialContextItem(Item item)
Set the initial context item.

When a transformation is invoked using the transform(Source,Result) method, the initial context node is set automatically. This method is useful in XQuery, to define an initial context node for evaluating global variables, and also in XSLT 2.0, when the transformation is started by invoking a named template.

When an initial context item is set, it also becomes the context item used for evaluating global variables. The two context items can only be different when the transform(Source,Result) method is used to transform a document starting at a node other than the root.

In XQuery, the two context items are always the same; in XSLT, the context node for evaluating global variables is the root of the tree containing the initial context item.

Parameters:
item - The initial context item. The XSLT specification says that this must be a node; however this restriction is not enforced, and any item can be supplied as an initial context item if the transformation is started by calling a named initial template. (There is no similar restriction in XQuery)
Since:
8.7

setInitialMode

public void setInitialMode(String expandedModeName)
Set the initial mode for the transformation.

XSLT 2.0 allows a transformation to be started in a mode other than the default mode. The transformation then starts by looking for the template rule in this mode that best matches the initial context node.

This method may eventually be superseded by a standard JAXP method.

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
Since:
8.4

setInitialTemplate

public void setInitialTemplate(String expandedName)
            throws XPathException
Set the initial named template to be used as the entry point.

XSLT 2.0 allows a transformation to start by executing a named template, rather than by matching an initial context node in a source document. This method may eventually be superseded by a standard JAXP method once JAXP supports XSLT 2.0.

Although the Saxon command line interface does not allow both a source document and an initial template to be specified, this API has no such restriction.

Note that any parameters supplied using setParameter are used as the values of global stylesheet parameters. There is no way to supply values for local parameters of the initial template.

Parameters:
expandedName - The expanded name of the template in {uri}local format, or null to indicate that there should be no initial template.
Throws:
XPathException - if there is no named template with this name
Since:
8.4

setMessageEmitter

public void setMessageEmitter(Receiver receiver)
Set the Receiver to be used for xsl:message output.

Recent versions of the JAXP interface specify that by default the output of xsl:message is sent to the registered ErrorListener. Saxon does not yet implement this convention. Instead, the output is sent to a default message emitter, which is a slightly customised implementation of the standard Saxon Emitter interface.

This interface can be used to change the way in which Saxon outputs xsl:message output.

It is not necessary to use this interface in order to change the destination to which messages are written: that can be achieved by obtaining the standard message emitter and calling its Emitter.setWriter(Writer) method.

This method is intended for use by advanced applications. The Receiver interface itself is subject to change in new Saxon releases.

The supplied Receiver will have its open() method called once at the start of the transformation, and its close() method will be called once at the end of the transformation. Each individual call of an xsl:message instruction is wrapped by calls of startDocument() and endDocument(). If terminate="yes" is specified on the xsl:message call, the properties argument of the startDocument() call will be set to the value ReceiverOptions.TERMINATE.

Parameters:
receiver - The receiver to receive xsl:message output.
Since:
8.4; changed in 8.9 to supply a Receiver rather than an Emitter

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.

As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in SaxonOutputKeys. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

Parameters:
properties - the output properties to be used for the transformation. If the value is null, the properties are reset to be the properties of the Templates object (that is, for XSLT 2.0, the properties set in the unnamed xsl:output object).
Since:
8.4

setOutputProperty

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

As well as the properties defined in the JAXP OutputKeys class, Saxon defines an additional set of properties in SaxonOutputKeys. These fall into two categories: Constants representing serialization properties defined in XSLT 2.0 (which are not yet supported by JAXP), and constants supporting Saxon extensions to the set of serialization properties.

Parameters:
name - the name of the property
value - the value of the property
Since:
8.4

setOutputURIResolver

public void setOutputURIResolver(OutputURIResolver resolver)
Set the URI resolver for secondary output documents.

XSLT 2.0 introduces the xsl:result-document

This method may eventually be superseded by a standard JAXP method.

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

setParameter

public void setParameter(String expandedName,
                         Object value)
Parameters:
expandedName - The name of the parameter in {uri}local format
value - The value object. This must follow the rules above. Other formats in addition to those listed above may be accepted.
Since:
8.4

setParameter

public void setParameter(StructuredQName qName,
                         ValueRepresentation value)
Supply a parameter using Saxon-specific representations of the name and value
Parameters:
qName - The structured representation of the parameter name
value - The value of the parameter, or null to remove a previously set value

setPreparedStylesheet

public void setPreparedStylesheet(PreparedStylesheet sheet)
Associate this Controller with a compiled stylesheet.

This method is intended for internal use only.

Parameters:
sheet - the compiled stylesheet

setPrincipalSourceDocument

public void setPrincipalSourceDocument(DocumentInfo doc)

Deprecated. From Saxon 8.7, replaced by setInitialContextItem(Item)

Set the initial context node (used for evaluating global variables). When a transformation is invoked using the transform(Source,Result) method, the initial context node is set automatically. This method is useful in XQuery, to define an initial context node for evaluating global variables, and also in XSLT 2.0, when the transformation is started by invoking a named template.
Parameters:
doc - The principal source document
Since:
8.4

setRecoveryPolicy

public void setRecoveryPolicy(int policy)
Set the policy for handling recoverable errrors
Since:
8.7.1

setRememberedNumber

public void setRememberedNumber(NodeInfo node,
                                int number)
Set the last remembered node, for node numbering purposes.

This method is strictly for internal use only.

Parameters:
node - the node in question
number - the number of this node

setRuleManager

public void setRuleManager(RuleManager r)
Set the RuleManager, used to manage template rules for each mode.

This method is intended for internal use only.

Parameters:
r - the Rule Manager

setSchemaURIResolver

public void setSchemaURIResolver(SchemaURIResolver resolver)
Set the SchemaURIResolver used for resolving references to schema documents. Defaults to the SchemaURIResolver registered with the Configuration
Parameters:
resolver - the resolver for references to schema documents

setThereHasBeenAnExplicitResultDocument

public void setThereHasBeenAnExplicitResultDocument()
Set that an explicit result tree has been written using xsl:result-document

setTreeModel

public void setTreeModel(int model)
Parameters:
model - the required tree model: Builder.LINKED_TREE or Builder.TINY_TREE
Since:
8.4
See Also:
Builder

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.

setUnparsedTextURIResolver

public void setUnparsedTextURIResolver(UnparsedTextURIResolver resolver)
Set an UnparsedTextURIResolver to be used to resolve URIs passed to the XSLT unparsed-text() function.
Parameters:
resolver - the unparsed text URI resolver to be used. This replaces any unparsed text URI resolver previously registered.
Since:
8.9

setUseDocumentProjection

public void setUseDocumentProjection(PathMap pathMap)
Indicate whether document projection should be used, and supply the PathMap used to control it. Note: this is available only under Saxon-SA.
Parameters:
pathMap - a path map to be used for projecting source documents

setUserData

public void setUserData(Object key,
                        String name,
                        Object data)
Set user data associated with a key. To store user data, two objects are required: an arbitrary object that may be regarded as the container of the data (originally, and typically still, a node in a tree), and a name. The name serves to distingush data objects associated with the same node by different client applications.

This method is intended primarily for internal use, though it may also be used by advanced applications.

Parameters:
key - an object acting as a key for this user data value. This must be equal (in the sense of the equals() method) to the key supplied when the data value was registered using setUserData(Object,String,Object). If data for the given object and name already exists, it is overwritten.
name - the name of the required property
data - the value of the required property

transform

public void transform(Source source,
                      Result result)
            throws 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.

transformDocument

public void transformDocument(NodeInfo startNode,
                              Result result)
            throws TransformerException
Transform a source XML document supplied as a tree.

This method is intended for internal use. External applications should use the transform(Source,Result) method, which is part of the JAXP interface. Note that NodeInfo implements the JAXP Source interface, so it may be supplied directly to the transform() method.

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

unravel

public static NodeInfo unravel(Source source,
                               Configuration config)

Deprecated. since 9.0: use Configuration.unravel(Source)

Get a NodeInfo corresponding to a DOM Node, either by wrapping or unwrapping the DOM Node.

This method is intended for internal use.

Parameters:
source - the wrapped or unwrapped DOM Node
config - the Saxon configuration
Returns:
a Saxon NodeInfo object obtained by wrapping or unwrapping the supplied DOM node.