public class XsltTransformer extends AbstractXsltTransformer implements Destination
XsltTransformer
represents a compiled and loaded stylesheet ready for execution.
The XsltTransformer
holds details of the dynamic evaluation context for the stylesheet.
An 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.
An XsltTransformer
is always constructed by running the Load
method of an XsltExecutable
.
An XsltTransformer
is itself a Destination
. This means it is possible to use
one 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.)
baseOutputUriWasSet, controller, processor
Modifier | Constructor and Description |
---|---|
protected |
XsltTransformer(Processor processor,
XsltController controller,
GlobalParameterSet staticParameters)
Protected constructor
|
Modifier and Type | Method and Description |
---|---|
void |
clearParameters()
Clear the values of all parameters that have been set
|
void |
close()
Close this destination, allowing resources to be released.
|
void |
closeAndNotify()
Close the destination and notify all registered listeners that it has been closed.
|
Destination |
getDestination()
Get the destination that was specified in a previous call of
setDestination(net.sf.saxon.s9api.Destination) |
java.net.URI |
getDestinationBaseURI()
Get the base URI of the resource being written to this destination
|
XdmNode |
getInitialContextNode()
Get the initial context node for the transformation, if one has been set
|
QName |
getInitialTemplate()
Get the initial named template for the transformation, if one has been set
|
XdmValue |
getParameter(QName name)
Get the value that has been set for a stylesheet parameter
|
Receiver |
getReceiver(PipelineConfiguration pipe,
SerializationProperties params)
Return a Receiver which can be used to supply the principal source document for the transformation.
|
void |
onClose(Action listener)
Register a listener to be notified when a
Outputter linked to this destination is closed. |
void |
setDestination(Destination destination)
Set the destination to be used for the result of the transformation.
|
void |
setDestinationBaseURI(java.net.URI baseURI)
Set the base URI of the resource being written to this destination
|
void |
setInitialContextNode(XdmNode node)
Set the initial context node for the transformation.
|
void |
setInitialTemplate(QName templateName)
Set the initial named template for the transformation
|
void |
setParameter(QName name,
XdmValue value)
Set the value of a stylesheet parameter.
|
void |
setSource(javax.xml.transform.Source source)
Set the source document for the transformation.
|
void |
transform()
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 processorcontroller
- the Saxon controller objectstaticParameters
- the static parameters supplied at stylesheet compile timepublic void setDestinationBaseURI(java.net.URI baseURI)
setDestinationBaseURI
in interface Destination
baseURI
- the base URI to be usedpublic java.net.URI getDestinationBaseURI()
getDestinationBaseURI
in interface Destination
public void onClose(Action listener)
Destination
Outputter
linked to this destination is closed.
Example: 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.
onClose
in interface Destination
listener
- an object to be notified when writing to the destination
is successfully completedpublic void closeAndNotify() throws SaxonApiException
Destination
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.closeAndNotify
in interface Destination
SaxonApiException
- if the close() method throws SaxonApiException
.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
of StreamSource
or SAXSource
.
Some kinds of Source
(for example StreamSource
and
SAXSource
are 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 transform()
.
source
- the principal source document for the transformationpublic 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 nodeSaxonApiUncheckedException
- if the node is unsuitable, for example if it was
built using the wrong Configurationpublic XdmNode getInitialContextNode()
XdmNode
instance as was supplied, but it will be an XdmNode object that represents
the same underlying node.public void setParameter(QName name, XdmValue value)
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
with 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
using XsltCompiler.setParameter(QName, XdmValue)
.
name
- the name of the stylesheet parameter, as a QNamevalue
- the value of the stylesheet parameter, or null to clear a previously set valueSaxonApiUncheckedException
- if the value is lazily evaluated, and evaluation failspublic void clearParameters()
public XdmValue getParameter(QName name)
name
- the parameter whose name is requiredpublic void setDestination(Destination destination)
This method can be used to chain transformations into a pipeline, by using one
XsltTransformer
as the destination of another
The Destination
object will generally be modified by a transformation
(that is, by a call on transform()
), and in general a Destination
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 transformationpublic Destination getDestination()
setDestination(net.sf.saxon.s9api.Destination)
public void transform() throws SaxonApiException
Calling this method will in general consume any Source
and Destination
that have been supplied, so a new Source
and 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
transformation completes.
If no source has been supplied (using setSource(Source)
), then the method
looks to see whether an initial named template has been supplied (using setInitialTemplate(QName)
,
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 transformationjava.lang.IllegalStateException
- if no destination has been suppliedpublic 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
XsltTransformer
implements 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 XsltTransformer
using setInitialContextNode(XdmNode)
is ignored,
as is the source set using setSource(javax.xml.transform.Source)
.
getReceiver
in interface Destination
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 createdjava.lang.IllegalStateException
- if no Destination has been suppliedpublic void close()
close
in interface Destination
Copyright (c) 2004-2022 Saxonica Limited. All rights reserved.