public class XsltTransformer extends AbstractXsltTransformer implements Destination
XsltTransformerrepresents a compiled and loaded stylesheet ready for execution. The
XsltTransformerholds details of the dynamic evaluation context for the stylesheet.
XsltTransformer must not be used concurrently in multiple threads.
It is safe, however, to reuse the object within a single thread to run the same
stylesheet several times. Running the stylesheet does not change the context
that has been established. Some of the public methods are synchronized: this is not because
multi-threaded execution is supported, rather it is to reduce the damage if multi-threaded
execution is attempted.
XsltTransformer is always constructed by running the
method of an
XsltTransformer is itself a
Destination. This means it is possible to use
XsltTransformer as the destination to receive the results of another transformation,
this providing a simple way for transformations to be chained into a pipeline. Note however that a
when the input to a transformation is supplied in this way, it will always be built as a tree in
memory, rather than the transformation being streamed. As a
Destination, the transformer
performs Sequence Normalization on its input; that is, it converts the input to a single
document node. (The main reason for this is that when chaining XSLT transformations, the raw
output of the first stylesheet is often an element node, but the second stylesheet traditionally
expects a document node.)
|Modifier||Constructor and Description|
|Modifier and Type||Method and Description|
Clear the values of all parameters that have been set
Close this destination, allowing resources to be released.
Close the destination and notify all registered listeners that it has been closed.
Get the destination that was specified in a previous call of
Get the base URI of the resource being written to this destination
Get the initial context node for the transformation, if one has been set
Get the initial named template for the transformation, if one has been set
Get the value that has been set for a stylesheet parameter
Return a Receiver which can be used to supply the principal source document for the transformation.
Register a listener to be notified when a
Set the destination to be used for the result of the transformation.
Set the base URI of the resource being written to this destination
Set the initial context node for the transformation.
Set the initial named template for the transformation
Set the value of a stylesheet parameter.
Set the source document for the transformation.
Perform the transformation.
applyTemplatesToSource, getBaseOutputURI, getDestinationReceiver, getErrorListener, getErrorReporter, getInitialMode, getMessageListener2, getReceivingTransformer, getResourceResolver, getSchemaValidationMode, getTraceFunctionDestination, getTraceListener, getUnderlyingController, getUnparsedTextURIResolver, getURIResolver, isAssertionsEnabled, isStreamableSource, setAssertionsEnabled, setBaseOutputURI, setErrorListener, setErrorReporter, setInitialMode, setMessageHandler, setMessageListener, setResourceResolver, setResultDocumentHandler, setSchemaValidationMode, setTraceFunctionDestination, setTraceListener, setUnparsedTextResolver, setURIResolver
protected XsltTransformer(Processor processor, XsltController controller, GlobalParameterSet staticParameters)
processor- the S9API processor
controller- the Saxon controller object
staticParameters- the static parameters supplied at stylesheet compile time
public void setDestinationBaseURI(java.net.URI baseURI)
public java.net.URI getDestinationBaseURI()
public void onClose(Action listener)
Outputterlinked to this destination is closed.
destination.onClose(() -> System.out.println("Finished writing to " + uri)
The method must be called before the call on
Destination.getReceiver(PipelineConfiguration, SerializationProperties); the
effect of calling it after getting a
Receiver, but before closing the
Outputter, is undefined.
public void closeAndNotify() throws SaxonApiException
Destination.close()to close the destination, then it calls
Consumer.accept(T)on each of the listeners in turn to notify the fact that it has been closed.
public void setInitialTemplate(QName templateName)
templateName- the name of the initial template, or null to indicate that there should be no initial named template. Changed in 9.9: the method no longer checks that the named template exists.
public QName getInitialTemplate()
public void setSource(javax.xml.transform.Source source)
If the source is an instance of
NodeInfo, the supplied node is used
directly as the initial context item of the transformation.
If the source is an instance of
DOMSource, the DOM node identified
by the DOMSource is wrapped as a Saxon node, and this is then used as the context item.
In other cases a new Saxon tree will be built by the transformation engine when the transformation starts, unless it is a Saxon-EE streaming transformation, in which case the document is processed in streaming fashion as it is being parsed.
To run a transformation in streaming mode, the source should be supplied as an instance
Some kinds of
Source (for example
SAXSourceare consumed by use; others (such as
DOMSource) are immutable.
In the general case, therefore, the
Source object that is supplied by this method
does not survive a call on
source- the principal source document for the transformation
public void setInitialContextNode(XdmNode node) throws SaxonApiUncheckedException
In XSLT 3.0 terms, this sets the initial match selection (the sequence to which the initial implicit call of xsl:applyTemplates is applied). It also determines how the global context item for evaluating global variables is set: following the XSLT 1.0 and 2.0 rules (XSLT 2.0 section 9.5): "For a global variable or the default value of a stylesheet parameter, the expression or sequence constructor specifying the variable value is evaluated with a singleton focus based on the root node of the tree containing the initial context node."
This value is ignored in the case where the
XsltTransformer is used as the
Destination of another process. In that case the initial context node will always
be the document node of the document that is being streamed to this destination.
Calling this method has the side-effect of setting the initial source to null.
node- the initial context node, or null if there is to be no initial context node
SaxonApiUncheckedException- if the node is unsuitable, for example if it was built using the wrong Configuration
public XdmNode getInitialContextNode()
XdmNodeinstance as was supplied, but it will be an XdmNode object that represents the same underlying node.
If the stylesheet does not have a parameter with this name, then the supplied value will simply be ignored (no error occurs)
If the stylesheet has a parameter with this name, and the supplied value does not match the required type, then no error will be reported at this stage, but a dynamic error will occur when the parameter value is first used. Supplied values are converted to the required type using the function conversion rules.
If the stylesheet has a parameter with this name, and the parameter is declared
static="yes", or if a parameter with the same name was supplied to the
XsltCompiler, then no error will be reported at this stage, but an error
will be reported when the transformation is initiated. Static parameters must be initialized
name- the name of the stylesheet parameter, as a QName
value- the value of the stylesheet parameter, or null to clear a previously set value
SaxonApiUncheckedException- if the value is lazily evaluated, and evaluation fails
public void clearParameters()
name- the parameter whose name is required
public void setDestination(Destination destination)
This method can be used to chain transformations into a pipeline, by using one
XsltTransformer as the destination of another
Destination object will generally be modified by a transformation
(that is, by a call on
transform()), and in general a
cannot be used more than once. Therefore, if this
XsltTransformer is used
for multiple transformations then a new
Destination should be set for each one.
destination- the destination to be used for the result of this transformation
public Destination getDestination()
public void transform() throws SaxonApiException
Calling this method will in general consume any
that have been supplied, so a new
Destination are needed for each
transformation. Other properties of this
XsltTransformer (for example, the values
of parameters, the initial template, and initial mode) are left unchanged after the
If no source has been supplied (using
setSource(Source)), then the method
looks to see whether an initial named template has been supplied (using
and if so, the transformation starts with that named template. In the absence of an initial named template,
it looks to see if the stylesheet includes a template named
xsl:initial-template, and if so,
uses that as the entry point. If there is no source and no initial template, the method fails.
SaxonApiException- if any dynamic error occurs during the transformation
java.lang.IllegalStateException- if no destination has been supplied
public Receiver getReceiver(PipelineConfiguration pipe, SerializationProperties params) throws SaxonApiException
Saxon calls this method to obtain a Receiver, to which it then sends
a sequence of events representing the content of an XML document. This method is provided so that
Destination, allowing one transformation
to receive the results of another in a pipeline.
Before calling this method, the
setDestination(net.sf.saxon.s9api.Destination) method must be called to supply a destination
for the transformation.
Note that when an
XsltTransformer is used as a
Destination, the initial
context node set on that
setInitialContextNode(XdmNode) is ignored,
as is the source set using
pipe- The Saxon configuration. This is supplied so that the destination can use information from the configuration (for example, a reference to the name pool) to construct or configure the returned Receiver.
params- serialization parameters (not relevant here since we aren't serializing; except possibly for the item-separator property)
SaxonApiException- if the Receiver cannot be created
java.lang.IllegalStateException- if no Destination has been supplied
Copyright (c) 2004-2022 Saxonica Limited. All rights reserved.