net.sf.saxon.trans

Class XsltController

java.lang.Object

net.sf.saxon.Controller

net.sf.saxon.trans.XsltController

All Implemented Interfaces:

ContextOriginator

public class XsltController
extends Controller

This class is an extension of the Controller class, used when executing XSLT stylesheets.

Since:

9.9

Field Summary

Fields inherited from class net.sf.saxon.Controller

ANONYMOUS_PRINCIPAL_OUTPUT_URI, errorListener, executable, globalContextItem, inUse, principalResult, principalResultURI, traceListener, validationMode

Constructor Summary

Constructors

Constructor and Description
XsltController(Configuration config, PreparedStylesheet pss)

Method Summary

Modifier and Type	Method and Description
void	addUnavailableOutputDestination(DocumentURI 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	applyStreamingTemplates(Source source, Receiver out) Perform a transformation by applying templates in a streamable mode to a streamable input document.
void	applyTemplates(Sequence<?> source, Receiver out) Perform a transformation from a Source document to a Result document.
void	callTemplate(StructuredQName initialTemplateName, Receiver out) Execute a transformation by evaluating a named template and delivering the "raw result".
boolean	checkUniqueOutputDestination(DocumentURI uri) Check that an output destination has not been used before, optionally adding this URI to the set of URIs that have been used.
protected void	clearPerTransformationData() Reset variables that need to be reset for each transformation if the controller is serially reused
AccumulatorManager	getAccumulatorManager() Get the accumulator manager for this transformation.
Stack<AttributeSet>	getAttributeSetEvaluationStack() Get the stack of attribute sets being evaluated (for detection of cycles)
PrincipalOutputGatekeeper	getGatekeeper() Get the Gatekeeper object, which is used to ensure that we don't write a secondary result document to the same destination as the principal result document
Mode	getInitialMode() Get the initial mode for the transformation
StructuredQName	getInitialModeName() Get the name of the initial mode for the transformation
Map<StructuredQName,Sequence<?>>	getInitialTemplateParameters(boolean tunnel) Get the parameters for the initial template
Map<StructuredQName,Integer>	getMessageCounters() Get the message counters
Receiver	getMessageEmitter() Deprecated. since 9.9.0.2; always returns null.
OutputURIResolver	getOutputURIResolver() Get the output URI resolver.
Destination	getPrincipalDestination() Get the principal destination that was supplied to the Controller
int	getRecoveryPolicy() Get the policy for handling recoverable errors
ResultDocumentResolver	getResultDocumentResolver()
Receiver	getStreamingReceiver(Mode mode, Receiver result) Get a receiver to which the input to this transformation can be supplied as a stream of events, causing the transformation to be executed in streaming mode.
void	incrementMessageCounter(StructuredQName code) Increment a counter in the message counters.
boolean	isAssertionsEnabled() Ask whether assertions (xsl:assert instructions) have been enabled at run time.
boolean	isUnusedOutputDestination(DocumentURI uri) Determine whether an output URI is available for use.
Receiver	makeMessageReceiver() Make a Receiver to be used for xsl:message output.
void	preEvaluateGlobals(XPathContext context) Pre-evaluate global variables (when debugging/tracing).
void	recoverableError(XPathException err) Report a recoverable error.
void	releaseAttributeSetEvaluationStack()
void	removeUnavailableOutputDestination(DocumentURI uri) Remove a URI from the set of output destinations that cannot be written to or read from.
void	reset() Reset this Transformer to its original configuration.
void	setAssertionsEnabled(boolean enabled) Ask whether assertions (xsl:assert instructions) have been enabled at run time.
void	setInitialMode(StructuredQName expandedModeName) Set the initial mode for the transformation.
void	setInitialTemplateParameters(Map<StructuredQName,Sequence<?>> params, boolean tunnel) Set parameters for the initial template (whether this is a named template, or a template rule invoked to process the initial input item)
void	setMessageEmitter(Receiver receiver) Set the Receiver to be used for xsl:message output.
void	setMessageFactory(Supplier<Receiver> messageReceiverFactory) Supply a factory function that is called every time xsl:message is executed; the factory function is responsible for creating a Receiver that receives the content of the message, and does what it will with it.
void	setMessageReceiverClassName(String name) Set the message receiver class name.
void	setOutputURIResolver(OutputURIResolver resolver) Set the URI resolver for secondary output documents.
void	setPrincipalDestination(Destination destination) Supply the Controller with information about the principal destination of the transformation
void	setRecoveryPolicy(int policy) Set the policy for handling recoverable XSLT errors.
void	setResultDocumentResolver(ResultDocumentResolver resultDocumentResolver)

Methods inherited from class net.sf.saxon.Controller

addTraceListener, allocateSequenceOutputter, allocateSequenceOutputter, checkReadiness, clearDocumentPool, clearGlobalContextItem, getBaseOutputURI, getBindery, getCollectionFinder, getCollectionURIResolver, getConfiguration, getConvertedParameter, getCurrentDateTime, getDefaultCollection, getDocumentPool, getErrorListener, getExecutable, getFocusTrackerFactory, getGlobalContextItem, getImplicitTimezone, getLocalIndexes, getModel, getParameter, getPathMapForDocumentProjection, getPrincipalResult, getRememberedNumber, getRuleManager, getSchemaValidationMode, getSpaceStrippingRule, getStandardURIResolver, getStylesheetCache, getTraceFunctionDestination, getTraceListener, getUnparsedTextURIResolver, getURIResolver, getUserData, initializeController, isStripSourceTree, isStylesheetContainingStripSpace, isStylesheetStrippingTypeAnnotations, isTracing, makeBuilder, makePipelineConfiguration, makeSourceTree, makeStripper, newXPathContext, pauseTracing, prepareInputTree, registerDocument, registerGlobalVariableDependency, removeTraceListener, reportFatalError, setApplyFunctionConversionRulesToExternalVariables, setBaseOutputURI, setCollectionFinder, setCollectionURIResolver, setCurrentDateTime, setDefaultCollection, setErrorListener, setFocusTrackerFactory, setGlobalContextItem, setGlobalContextItem, setMemoizingFocusTrackerFactory, setModel, setMultithreadedFocusTrackerFactory, setRememberedNumber, setSchemaValidationMode, setStripSourceTrees, setTraceFunctionDestination, setTraceListener, setUnparsedTextURIResolver, setURIResolver, setUseDocumentProjection, setUserData, warning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XsltController

public XsltController(Configuration config,
                      PreparedStylesheet pss)

Method Detail

reset

public void reset()

Reset this Transformer to its original configuration.

Transformer is reset to the same state as when it was created with TransformerFactory.newTransformer(), TransformerFactory.newTransformer(javax.xml.transform.Source source) or Templates.newTransformer(). reset() is designed to allow the reuse of existing Transformers thus saving resources associated with the creation of new Transformers.

The above is from the JAXP specification. With Saxon, it's unlikely that reusing a Transformer will give any performance benefits over creating a new one. The one case where it might be beneficial is to reuse the document pool (the set of documents that have been loaded using the doc() or document() functions). Therefore, this method does not clear the document pool. If you want to clear the document pool, call the method Controller.clearDocumentPool() as well.

The reset Transformer is not guaranteed to have the same URIResolver or ErrorListener Objects, e.g. Object.equals(Object obj). It is guaranteed to have a functionally equal URIResolver and ErrorListener.

Overrides:

reset in class Controller

Since:

1.5

clearPerTransformationData

protected void clearPerTransformationData()

Reset variables that need to be reset for each transformation if the controller is serially reused

Overrides:

clearPerTransformationData in class Controller

setInitialMode

public void setInitialMode(StructuredQName expandedModeName)
                    throws XPathException

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. Two special values are recognized, in the reserved XSLT namespace: xsl:unnamed to indicate the mode with no name, and xsl:default to indicate the mode defined in the stylesheet header as the default mode. The value null also indicates the unnamed mode.

Throws:

XPathException - if the requested mode is not defined in the stylesheet

Since:

8.4 Changed in 9.6 to accept a StructuredQName, and to throw an error if the mode has not been defined. Changed in 9.7 so that null indicates the default mode, which defaults to the unnamed mode but can be set otherwise in the stylesheet.

getInitialModeName

public StructuredQName getInitialModeName()

Get the name of the initial mode for the transformation

Returns:

the name of the initial mode; null indicates that the initial mode is the unnamed mode.

getInitialMode

public Mode getInitialMode()

Get the initial mode for the transformation

Returns:

the initial mode. This will be the default/unnamed mode if no specific mode has been requested

getAccumulatorManager

public AccumulatorManager getAccumulatorManager()

Get the accumulator manager for this transformation. May be null if no accumulators are in use

Returns:

the accumulator manager, which holds dynamic information about the values of each accumulator for each document

checkUniqueOutputDestination

public boolean checkUniqueOutputDestination(DocumentURI uri)

Check that an output destination has not been used before, optionally adding this URI to the set of URIs that have been used.

This method is intended for internal use only.

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.

addUnavailableOutputDestination

public void addUnavailableOutputDestination(DocumentURI 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

removeUnavailableOutputDestination

public void removeUnavailableOutputDestination(DocumentURI 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

isUnusedOutputDestination

public boolean isUnusedOutputDestination(DocumentURI 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.

setInitialTemplateParameters

public void setInitialTemplateParameters(Map<StructuredQName,Sequence<?>> params,
                                         boolean tunnel)

Set parameters for the initial template (whether this is a named template, or a template rule invoked to process the initial input item)

Parameters:

params - Tunnel or non-tunnel parameters to be supplied to the initial template. The supplied values will be converted to the required type using the function conversion rules. Any surplus parameters are silently ignored. May be null.

tunnel - true if these are tunnel parameters; false if they are non-tunnel parameters

Since:

9.6

getInitialTemplateParameters

public Map<StructuredQName,Sequence<?>> getInitialTemplateParameters(boolean tunnel)

Get the parameters for the initial template

Parameters:

tunnel - true if the parameters to be returned are the tunnel parameters; false for the non-tunnel parameters

Returns:

the parameters supplied using setInitialTemplateParameters(Map, boolean). May be null.

Since:

9.6

setMessageFactory

public void setMessageFactory(Supplier<Receiver> messageReceiverFactory)

Supply a factory function that is called every time xsl:message is executed; the factory function is responsible for creating a Receiver that receives the content of the message, and does what it will with it.

Parameters:

messageReceiverFactory - a factory function whose job it is to create a Receiver for xsl:message output; the function should supply a new Receiver each time it is called, because xsl:message calls may arise in different threads and the Receiver is unlikely to be thread-safe.

setMessageReceiverClassName

public void setMessageReceiverClassName(String name)

Set the message receiver class name. This is an alternative way (retained for compatibility) of providing a factory for message receivers; it causes a message factory to be established that instantiates the supplied class

Parameters:

name - the full name of the class to be instantiated to provide a receiver for xsl:message output. The name must be the name of a class that implements the Receiver interface

makeMessageReceiver

public Receiver makeMessageReceiver()
                             throws XPathException

Make a Receiver to be used for xsl:message output.

This method is intended for internal use only. From 9.9.0.2 (bug 3979) this method is called to obtain a new Receiver each time an xsl:message instruction is evaluated.

Returns:

The newly constructed message Receiver

Throws:

XPathException - if any dynamic error occurs; in particular, if the registered MessageEmitter class is not an Emitter

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 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(java.io.Writer) method.

Although any Receiver can be supplied as the destination for messages, applications may find it convenient to implement a subclass of SequenceWriter, in which only the abstract write() method is implemented. This will have the effect that the write() method is called to output each message as it is generated, with the Item that is passed to the write() method being the document node at the root of an XML document containing the contents of the message.

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. Changed in 9.9.0.2 so it is no longer supported in a configuration that allows multi-threading.

getMessageEmitter

public Receiver getMessageEmitter()

Deprecated. since 9.9.0.2; always returns null.

Get the Receiver used for xsl:message output. This returns the emitter previously supplied to the setMessageEmitter(net.sf.saxon.event.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

incrementMessageCounter

public void incrementMessageCounter(StructuredQName code)

Increment a counter in the message counters. This method is called automatically when xsl:message is executed, to increment the counter associated with a given error code used in the xsl:message. The counters are available (in Saxon-PE and -EE) using the saxon:message-counter() extension function.

Parameters:

code - the error code whose counter is to be incremented

getMessageCounters

public Map<StructuredQName,Integer> getMessageCounters()

Get the message counters

Returns:

a snapshot copy of the table of message counters, indicating the number of times xsl:message has been called for each distinct error code

setRecoveryPolicy

public void setRecoveryPolicy(int policy)

Set the policy for handling recoverable XSLT errors.

Since 9.3 this call has no effect unless the error listener in use is a StandardErrorListener or a subclass thereof. Calling this method then results in a call to the StandardErrorListener to set the recovery policy, and the action that is taken on calls of the various methods error(), fatalError(), and warning() is then the responsibility of the ErrorListener itself.

Since 9.2 the policy for handling the most common recoverable error, namely the ambiguous template match that arises when a node matches more than one match pattern, is a compile-time rather than run-time setting, and can be controlled using CompilerInfo.setRecoveryPolicy(int)

Parameters:

policy - the recovery policy to be used. The options are Configuration.RECOVER_SILENTLY, Configuration.RECOVER_WITH_WARNINGS, or Configuration.DO_NOT_RECOVER.

Since:

8.7.1

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

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.

Overrides:

recoverableError in class Controller

Parameters:

err - An exception holding information about the error

Throws:

XPathException - if the error listener decides not to recover from the error

setOutputURIResolver

public void setOutputURIResolver(OutputURIResolver resolver)

Set the URI resolver for secondary output documents.

XSLT 2.0 introduces the xsl:result-document instruction, allowing a transformation to have multiple result documents. JAXP does not yet support this capability. This method allows an OutputURIResolver to be specified that takes responsibility for deciding the destination (and, if it wishes, the serialization properties) of secondary output files.

In Saxon 9.5, because xsl:result-document is now multi-threaded, the supplied resolver is cloned each time a new result document is created. The cloned resolved is therefore able to maintain information about the specific result document for use when its close() method is called, without worrying about thread safety.

Parameters:

resolver - An object that implements the OutputURIResolver interface, or null.

Since:

8.4. Retained for backwards compatibility in 9.9, but superseded by setResultDocumentResolver(ResultDocumentResolver)

getResultDocumentResolver

public ResultDocumentResolver getResultDocumentResolver()

setResultDocumentResolver

public void setResultDocumentResolver(ResultDocumentResolver resultDocumentResolver)

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. Retained for backwards compatibility in 9.9; superseded by getResultDocumentResolver()

See Also:

setOutputURIResolver(net.sf.saxon.lib.OutputURIResolver)

setPrincipalDestination

public void setPrincipalDestination(Destination destination)

Supply the Controller with information about the principal destination of the transformation

Parameters:

destination - the principal destination

getPrincipalDestination

public Destination getPrincipalDestination()

Get the principal destination that was supplied to the Controller

Returns:

the principal destination

isAssertionsEnabled

public boolean isAssertionsEnabled()

Ask whether assertions (xsl:assert instructions) have been enabled at run time. By default they are disabled at compile time. If assertions are enabled at compile time, then by default they will also be enabled at run time; but they can be disabled at run time by specific request. At compile time, assertions can be enabled for some packages and disabled for others; at run-time, they can only be enabled or disabled globally.

Returns:

true if assertions are enabled at run time

Since:

9.7

setAssertionsEnabled

public void setAssertionsEnabled(boolean enabled)

Ask whether assertions (xsl:assert instructions) have been enabled at run time. By default they are disabled at compile time. If assertions are enabled at compile time, then by default they will also be enabled at run time; but they can be disabled at run time by specific request. At compile time, assertions can be enabled for some packages and disabled for others; at run-time, they can only be enabled or disabled globally.

Parameters:

enabled - true if assertions are to be enabled at run time; this has no effect if assertions were disabled (for a particular package) at compile time

Since:

9.7

preEvaluateGlobals

public void preEvaluateGlobals(XPathContext context)
                        throws XPathException

Description copied from class: Controller

Pre-evaluate global variables (when debugging/tracing).

This method is intended for internal use.

Overrides:

preEvaluateGlobals in class Controller

Parameters:

context - the dynamic context for evaluating the global variables

Throws:

XPathException

applyTemplates

public void applyTemplates(Sequence<?> source,
                           Receiver out)
                    throws XPathException

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.

out - The destination for the result sequence. The events that are written to this Receiver will form a regular event sequence as defined in RegularSequenceChecker. This event sequence represents the raw results of the transformation; subsequent processing such as sequence normalization (to construct a document node) is the responsibility of the Receiver itself.

Throws:

XPathException - if the transformation fails. As a special case, the method throws a TerminationException (a subclass of XPathException) if the transformation was terminated using xsl:message terminate="yes".

getGatekeeper

public PrincipalOutputGatekeeper getGatekeeper()

Get the Gatekeeper object, which is used to ensure that we don't write a secondary result document to the same destination as the principal result document

Returns:

the gatekeeper object, or null if none is in use

callTemplate

public void callTemplate(StructuredQName initialTemplateName,
                         Receiver out)
                  throws XPathException

Execute a transformation by evaluating a named template and delivering the "raw result".

If any child threads are started (as a result of calls to xsl:result-document) the method will wait for these to finish before returning to the caller.

Parameters:

initialTemplateName - the entry point, the name of a named template

out - The destination for the result sequence. The events that are written to this Receiver will form a regular event sequence as defined in RegularSequenceChecker. This event sequence represents the raw results of the transformation; subsequent processing such as sequence normalization (to construct a document node) is the responsibility of the Receiver itself.

Throws:

XPathException - if any dynamic error occurs (in this thread or in a child thread). This includes the case where the named template does not exist.

applyStreamingTemplates

public void applyStreamingTemplates(Source source,
                                    Receiver out)
                             throws XPathException

Perform a transformation by applying templates in a streamable mode to a streamable input document.

Parameters:

source - The input for the source tree. Must be (or resolve to) a StreamSource or SAXSource.

out - The destination for the result sequence. The events that are written to this Receiver will form a regular event sequence as defined in RegularSequenceChecker. This event sequence represents the raw results of the transformation; subsequent processing such as sequence normalization (to construct a document node) is the responsibility of the Receiver itself.

Throws:

XPathException - if the transformation fails. As a special case, the method throws a TerminationException (a subclass of XPathException) if the transformation was terminated using xsl:message terminate="yes".

getStreamingReceiver

public Receiver getStreamingReceiver(Mode mode,
                                     Receiver result)
                              throws XPathException

Get a receiver to which the input to this transformation can be supplied as a stream of events, causing the transformation to be executed in streaming mode.

Parameters:

mode - the initial mode, which must be a streaming mode

result - The output destination

Returns:

a receiver to which events can be streamed

Throws:

XPathException - if any dynamic error occurs

getAttributeSetEvaluationStack

public Stack<AttributeSet> getAttributeSetEvaluationStack()

Get the stack of attribute sets being evaluated (for detection of cycles)

Returns:

the attribute set evaluation stack

releaseAttributeSetEvaluationStack

public void releaseAttributeSetEvaluationStack()