net.sf.saxon.s9api

Class Xslt30Transformer

java.lang.Object

net.sf.saxon.s9api.Xslt30Transformer

public class Xslt30Transformer
extends java.lang.Object

An Xslt30Transformer represents a compiled and loaded stylesheet ready for execution. The Xslt30Transformer holds details of the dynamic evaluation context for the stylesheet.

The Xslt30Transformer differs from XsltTransformer is supporting new options for invoking a stylesheet, corresponding to facilities defined in the XSLT 3.0 specification. However, it is not confined to use with XSLT 3.0, and most of the new invocation facilities (for example, calling a stylesheet-defined function directly) work equally well with XSLT 2.0 and in some cases XSLT 1.0 stylesheets.

An Xslt30Transformer must not be used concurrently in multiple threads. It is safe to reuse the object within a single thread to run several transformations using the same stylesheet, but the values of the global context item and of stylesheet parameters must be initialized before any transformations are run, and must remain unchanged thereafter.

An Xslt30Transformer is always constructed by running the Load30 method of an XsltExecutable.

Unlike XsltTransformer, an Xslt30Transformer is not a Destination. To pipe the results of one transformation into another, the target should be an XsltTransfomer rather than an Xslt30Transformer.

Evaluation of an Xslt30Transformer proceeds in a number of phases:

1. First, values may be supplied for stylesheet parameters and for the global context item. The global context item is used when initializing global variables. Unlike earlier transformation APIs, the global context item is quite independent of the "principal Source document".
2. The stylesheet may now be repeatedly invoked. Each invocation takes one of three forms:
   1. Invocation by applying templates. In this case, the information required is (i) an initial mode (which defaults to the unnamed mode), (ii) an initial match sequence, which is any XDM value, which is used as the effective "select" expression of the implicit apply-templates call, and (iii) optionally, values for the tunnel and non-tunnel parameters defined on the templates that get invoked (equivalent to using xsl:with-param on the implicit apply-templates call).
   2. Invocation by calling a named template. In this case, the information required is (i) the name of the initial template (which defaults to "xsl:initial-template"), and (ii) optionally, values for the tunnel and non-tunnel parameters defined on the templates that get invoked (equivalent to using xsl:with-param on the implicit call-template instruction).
   3. Invocation by calling a named function. In this case, the information required is the sequence of arguments to the function call.
3. Whichever invocation method is chosen, the result may either be returned directly, as an arbitrary XDM value, or it may effectively be wrapped in an XML document. If it is wrapped in an XML document, that document can be processed in a number of ways, for example it can be materialized as a tree in memory, it can be serialized as XML or HTML, or it can be subjected to further transformation.

Once the stylesheet has been invoked (using any of these methods), the values of the global context item and stylesheet parameters cannot be changed. If it is necessary to run another transformation with a different context item or different stylesheet parameters, a new Xslt30Transformer should be created from the original XsltExecutable.

Since:

9.6

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	baseOutputUriWasSet
protected XsltController	controller
protected Processor	processor

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Xslt30Transformer(Processor processor, XsltController controller, GlobalParameterSet staticParameters) Protected constructor

Method Summary

Modifier and Type	Method and Description
XdmValue	applyTemplates(javax.xml.transform.Source source) Invoke the stylesheet by applying templates to a supplied Source document, returning the raw results as an XdmValue.
void	applyTemplates(javax.xml.transform.Source source, Destination destination) Invoke the stylesheet by applying templates to a supplied Source document, sending the results (wrapped in a document node) to a given Destination.
XdmValue	applyTemplates(XdmValue selection) Invoke the stylesheet by applying templates to a supplied input sequence, returning the raw results.
void	applyTemplates(XdmValue selection, Destination destination) Invoke the stylesheet by applying templates to a supplied input sequence, sending the results (wrapped in a document node) to a given Destination.
protected void	applyTemplatesToSource(javax.xml.transform.Source source, Receiver out)
Destination	asDocumentDestination(Destination finalDestination) Construct a Destination object whose effect is to perform this transformation on any input that is sent to that Destination: for example, it allows this transformation to post-process the results of another transformation.
XdmValue	callFunction(QName function, XdmValue[] arguments) Call a public user-defined function in the stylesheet.
void	callFunction(QName function, XdmValue[] arguments, Destination destination) Call a public user-defined function in the stylesheet, wrapping the result in an XML document, and sending this document to a specified destination
XdmValue	callTemplate(QName templateName) Invoke a transformation by calling a named template.
void	callTemplate(QName templateName, Destination destination) Invoke a transformation by calling a named template.
java.lang.String	getBaseOutputURI() Get the base output URI.
Receiver	getDestinationReceiver(XsltController controller, Destination destination) Get a Receiver corresponding to the chosen Destination for the transformation
javax.xml.transform.ErrorListener	getErrorListener() Get the ErrorListener being used during this compilation episode
QName	getInitialMode() Get the name of the initial mode for the transformation, if one has been set.
MessageListener	getMessageListener() Get the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction.
MessageListener2	getMessageListener2() Get the MessageListener2 to be notified whenever the stylesheet evaluates an xsl:message instruction.
protected Receiver	getReceivingTransformer(XsltController controller, GlobalParameterSet parameters, Destination finalDestination) Return a Receiver which can be used to supply the principal source document for the transformation.
ValidationMode	getSchemaValidationMode() Get the schema validation mode for the transformation.
Logger	getTraceFunctionDestination() Get the destination for output from the fn:trace() function.
TraceListener	getTraceListener() Get the TraceListener to be notified of all events occurring during the transformation.
XsltController	getUnderlyingController() Get the underlying Controller used to implement this XsltTransformer.
javax.xml.transform.URIResolver	getURIResolver() Get the URI resolver.
boolean	isAssertionsEnabled() Ask whether assertions (xsl:assert instructions) have been enabled at run time.
protected boolean	isStreamableSource(javax.xml.transform.Source source)
Serializer	newSerializer() Create a serializer initialised to use the default output parameters defined in the stylesheet.
Serializer	newSerializer(java.io.File file) Create a serializer initialised to use the default output parameters defined in the stylesheet.
Serializer	newSerializer(java.io.OutputStream stream) Create a serializer initialised to use the default output parameters defined in the stylesheet.
Serializer	newSerializer(java.io.Writer writer) Create a serializer initialised to use the default output parameters defined in the stylesheet.
void	setAssertionsEnabled(boolean enabled) Say whether assertions (xsl:assert instructions) should be enabled at run time.
void	setBaseOutputURI(java.lang.String uri) Set the base output URI.
void	setErrorListener(javax.xml.transform.ErrorListener listener) Set the ErrorListener to be used during this transformation
void	setGlobalContextItem(XdmItem globalContextItem) Supply the context item to be used when evaluating global variables and parameters.
void	setGlobalContextItem(XdmItem globalContextItem, boolean alreadyStripped) Supply the context item to be used when evaluating global variables and parameters.
void	setInitialContextItem(XdmItem item) Deprecated. since 9.8 - use setGlobalContextItem(net.sf.saxon.s9api.XdmItem)
void	setInitialContextNode(XdmNode node) Deprecated. since 9.7.0.1 - use setGlobalContextItem(net.sf.saxon.s9api.XdmItem)
void	setInitialMode(QName modeName) Set the initial mode for the transformation
<T extends XdmValue> void	setInitialTemplateParameters(java.util.Map<QName,T> parameters, boolean tunnel) Set parameters to be passed to the initial template.
void	setMessageListener(MessageListener listener) Set the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction.
void	setMessageListener(MessageListener2 listener) Set the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction.
void	setResultDocumentHandler(java.util.function.Function<java.net.URI,Destination> handler) Set a callback function that will be used when xsl:result-document is evaluated.
void	setSchemaValidationMode(ValidationMode mode) Set the schema validation mode for the transformation.
<T extends XdmValue> void	setStylesheetParameters(java.util.Map<QName,T> parameters) Supply the values of global stylesheet parameters.
void	setTraceFunctionDestination(Logger stream) Set the destination for output from the fn:trace() function.
void	setTraceListener(TraceListener listener) Set a TraceListener to be notified of all events occurring during the transformation.
void	setURIResolver(javax.xml.transform.URIResolver resolver) Set an object that will be used to resolve URIs used in fn:doc() and related functions.
void	transform(javax.xml.transform.Source source, Destination destination) Invoke the stylesheet by applying templates to a supplied Source document, sending the results to a given Destination.

Methods inherited from class java.lang.Object

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

Field Detail

processor

protected Processor processor

controller

protected XsltController controller

baseOutputUriWasSet

protected boolean baseOutputUriWasSet

Constructor Detail

Xslt30Transformer

protected Xslt30Transformer(Processor processor,
                            XsltController controller,
                            GlobalParameterSet staticParameters)

Protected constructor

Parameters:

processor - the S9API processor

controller - the Saxon controller object

staticParameters - the static parameters supplied at stylesheet compile time

Method Detail

setGlobalContextItem

public void setGlobalContextItem(XdmItem globalContextItem)
                          throws SaxonApiException

Supply the context item to be used when evaluating global variables and parameters. A call on setGlobalContextItem(node) is equivalent to a call on setGlobalContextItem(node, false): that is, it is assumed that stripping of type annotations and whitespace text nodes has not yet been performed.

Note: It is more efficient to do whitespace stripping while constructing the source tree. This can be achieved by building the source tree using a DocumentBuilder initialized using DocumentBuilder.setWhitespaceStrippingPolicy(WhitespaceStrippingPolicy), supplying a WhitespaceStrippingPolicy obtained by calling XsltExecutable.getWhitespaceStrippingPolicy().

Parameters:

globalContextItem - the item to be used as the context item within the initializers of global variables and parameters. This argument can be null if no context item is to be supplied.

Throws:

java.lang.IllegalStateException - if the transformation has already been evaluated by calling one of the methods applyTemplates, callTemplate, or callFunction

SaxonApiException - if a required parameter is not present; if a parameter cannot be converted to the required type; if the context item cannot be converted to the required type.

setGlobalContextItem

public void setGlobalContextItem(XdmItem globalContextItem,
                                 boolean alreadyStripped)
                          throws SaxonApiException

Supply the context item to be used when evaluating global variables and parameters.

Parameters:

globalContextItem - the item to be used as the context item within the initializers of global variables and parameters. This argument can be null if no context item is to be supplied.

alreadyStripped - true if any stripping of type annotations or whitespace text nodes specified by the stylesheet has already taken place

Throws:

java.lang.IllegalStateException - if the transformation has already been evaluated by calling one of the methods applyTemplates, callTemplate, or callFunction

SaxonApiException - Not thrown, but retained in the method signature for compatibility reasons.

setInitialContextNode

public void setInitialContextNode(XdmNode node)

Deprecated. since 9.7.0.1 - use setGlobalContextItem(net.sf.saxon.s9api.XdmItem)

Set the initial context node for the transformation.

Parameters:

node - the initial context node, or null if there is to be no initial context node

setInitialContextItem

public void setInitialContextItem(XdmItem item)

Deprecated. since 9.8 - use setGlobalContextItem(net.sf.saxon.s9api.XdmItem)

Set the initial context item for the transformation.

Parameters:

item - the initial context item, or null if there is to be no initial context item

setStylesheetParameters

public <T extends XdmValue> void setStylesheetParameters(java.util.Map<QName,T> parameters)
                                                  throws SaxonApiException

Supply the values of global stylesheet parameters.

If a value is supplied for a parameter with a particular name, and the stylesheet does not declare a parameter with that name, then the value is simply ignored.

If a value is supplied for a parameter with a particular name, and the stylesheet declaration of that parameter declares a required type, then the supplied value will be checked against that type when the value of the parameter is first used (and any error will be reported only then). Parameter values are converted to the required type using the function conversion rules.

If a value is supplied for a parameter with a particular name, and the stylesheet declaration of that parameter declares it with the attribute static="yes", then an error will be reported when the transformation is initiated.

If a value is supplied for a parameter with a particular name, and a parameter with the same name was supplied at compile time using XsltCompiler.setParameter(QName, XdmValue), then an error will be reported with the transformation is initiated.

Parameters:

parameters - a map whose keys are QNames identifying global stylesheet parameters, and whose corresponding values are the values to be assigned to those parameters. The contents of the supplied map are copied by this method, so subsequent changes to the map have no effect.

Throws:

java.lang.IllegalStateException - if the transformation has already been evaluated by calling one of the methods applyTemplates, callTemplate, or callFunction

SaxonApiException - currently occurs only if the supplied value of a parameter cannot be evaluated

setInitialTemplateParameters

public <T extends XdmValue> void setInitialTemplateParameters(java.util.Map<QName,T> parameters,
                                                              boolean tunnel)
                                                       throws SaxonApiException

Set parameters to be passed to the initial template. These are used whether the transformation is invoked by applying templates to an initial source item, or by invoking a named template. The parameters in question are the xsl:param elements appearing as children of the xsl:template element.

The parameters are supplied in the form of a map; the key is a QName which must match the name of the parameter; the associated value is an XdmValue containing the value to be used for the parameter. If the initial template defines any required parameters, the map must include a corresponding value. If the initial template defines any parameters that are not present in the map, the default value is used. If the map contains any parameters that are not defined in the initial template, these values are silently ignored.

The supplied values are converted to the required type using the function conversion rules. If conversion is not possible, a run-time error occurs (not now, but later, when the transformation is actually run).

The XsltTransformer retains a reference to the supplied map, so parameters can be added or changed until the point where the transformation is run.

The XSLT 3.0 specification makes provision for supplying parameters to the initial template, as well as global stylesheet parameters. Although there is no similar provision in the XSLT 1.0 or 2.0 specifications, this method works for all stylesheets, regardless whether XSLT 3.0 is enabled or not.

Parameters:

parameters - the parameters to be used for the initial template

tunnel - true if these values are to be used for setting tunnel parameters; false if they are to be used for non-tunnel parameters

Throws:

SaxonApiException - not currently used, but retained in the method signature for compatibility reasons

applyTemplates

public void applyTemplates(javax.xml.transform.Source source,
                           Destination destination)
                    throws SaxonApiException

Invoke the stylesheet by applying templates to a supplied Source document, sending the results (wrapped in a document node) to a given Destination. The invocation uses any initial mode set using setInitialMode(QName), and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean).

This method does not set the global context item for the transformation. If that is required, it can be done separately using the method setGlobalContextItem(XdmItem).

Parameters:

source - the source document. For streamed processing, this must be a SAXSource or StreamSource.

Note: supplying a DOMSource is allowed, but is much less efficient than using a StreamSource or SAXSource and leaving Saxon to build the tree in its own internal format. To apply more than one transformation to the same source document, the source document tree can be pre-built using a DocumentBuilder.

destination - the destination of the principal result of the transformation. If the destination is a Serializer, then the serialization parameters set in the serializer are combined with those defined in the stylesheet (the parameters set in the serializer take precedence).

Throws:

SaxonApiException - if the transformation fails

applyTemplates

public XdmValue applyTemplates(javax.xml.transform.Source source)
                        throws SaxonApiException

Invoke the stylesheet by applying templates to a supplied Source document, returning the raw results as an XdmValue. The invocation uses any initial mode set using setInitialMode(QName), and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean).

Parameters:

source - the source document. For streamed processing, this must be a SAXSource or StreamSource.

Note: supplying a DOMSource is allowed, but is much less efficient than using a StreamSource or SAXSource and leaving Saxon to build the tree in its own internal format. To apply more than one transformation to the same source document, the source document tree can be pre-built using a DocumentBuilder.

Returns:

the raw result of processing the supplied Source using the selected template rule, without wrapping the returned sequence in a document node

Throws:

SaxonApiException - if the transformation fails

transform

public void transform(javax.xml.transform.Source source,
                      Destination destination)
               throws SaxonApiException

Invoke the stylesheet by applying templates to a supplied Source document, sending the results to a given Destination. The invocation uses the initial mode set using setInitialMode(QName) (defaulting to the default mode defined in the stylesheet itself, which by default is the unnamed mode). It also uses any template parameters set using setInitialTemplateParameters(java.util.Map, boolean).

The document supplied in the source argument also acts as the global context item for the transformation. Any item previously supplied using setGlobalContextItem(XdmItem) is ignored.

Because this method sets the global context item to the root node of the supplied source, it cannot be used when the stylesheet is designed to process streamed input. For streamed processing, use applyTemplates(Source, Destination) instead.

Parameters:

source - the source document.

Note: supplying a DOMSource is allowed, but is much less efficient than using a StreamSource or SAXSource and leaving Saxon to build the tree in its own internal format. To apply more than one transformation to the same source document, the source document tree can be pre-built using a DocumentBuilder.

destination - the destination of the principal result of the transformation. If the destination is a Serializer, then the serialization parameters set in the serializer are combined with those defined in the stylesheet (the parameters set in the serializer take precedence).

Throws:

SaxonApiException - if the transformation fails, or if the initial mode in the stylesheet is declared to be streamable.

Since:

9.9.1.1

applyTemplates

public void applyTemplates(XdmValue selection,
                           Destination destination)
                    throws SaxonApiException

Invoke the stylesheet by applying templates to a supplied input sequence, sending the results (wrapped in a document node) to a given Destination. The invocation uses any initial mode set using setInitialMode(QName), and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean).

Parameters:

selection - the initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates)

destination - the destination for the result document. In most cases this causes the raw result of the transformation to be wrapped in a document node. However, if the destination is a Serializer and the output method is "json" or "adaptive", then no wrapping takes place.

Throws:

SaxonApiException - if the transformation fails

Since:

9.6. Changed in 9.7.0.1 so that if a Serializer is supplied as the Destination, it will not be modified by this method to set output properties from the stylesheet; instead, the Serializer should be initialized by calling the newSerializer method on this Xslt30Transformer

applyTemplates

public XdmValue applyTemplates(XdmValue selection)
                        throws SaxonApiException

Invoke the stylesheet by applying templates to a supplied input sequence, returning the raw results. as an XdmValue. The invocation uses any initial mode set using setInitialMode(QName), and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean).

Parameters:

selection - the initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates)

Returns:

the raw result of applying templates to the supplied selection value, without wrapping in a document node or serializing the result. If there is more that one item in the selection, the result is the concatenation of the results of applying templates to each item in turn.

Throws:

SaxonApiException - if the transformation fails

callTemplate

public void callTemplate(QName templateName,
                         Destination destination)
                  throws SaxonApiException

Invoke a transformation by calling a named template. The results of calling the template are wrapped in a document node, which is then sent to the specified destination. If setInitialTemplateParameters(java.util.Map, boolean) has been called, then the parameters supplied are made available to the called template (no error occurs if parameters are supplied that are not used).

Parameters:

templateName - the name of the initial template. This must match the name of a public named template in the stylesheet. If the value is null, the QName xsl:initial-template is used.

destination - the destination for the result document.

Throws:

SaxonApiException - if there is no named template with this name, or if any dynamic error occurs during the transformation

Since:

9.6. Changed in 9.7.0.1 so that if a Serializer is supplied as the Destination, it will not be modified by this method to set output properties from the stylesheet; instead, the Serializer should be initialized by calling the newSerializer method on this Xslt30Transformer

callTemplate

public XdmValue callTemplate(QName templateName)
                      throws SaxonApiException

Invoke a transformation by calling a named template. The results of calling the template are returned as a raw value, without wrapping in a document node or serializing.

Parameters:

templateName - the name of the initial template. This must match the name of a public named template in the stylesheet. If the value is null, the QName xsl:initial-template is used.

Returns:

the raw results of the called template, without wrapping in a document node or serialization.

Throws:

SaxonApiException - if there is no named template with this name, or if any dynamic error occurs during the transformation

callFunction

public XdmValue callFunction(QName function,
                             XdmValue[] arguments)
                      throws SaxonApiException

Call a public user-defined function in the stylesheet.

Parameters:

function - The name of the function to be called

arguments - The values of the arguments to be supplied to the function. These will be converted if necessary to the type as defined in the function signature, using the function conversion rules.

Returns:

the result of calling the function. This is the raw result, without wrapping in a document node and without serialization.

Throws:

SaxonApiException - if no function has been defined with the given name and arity; or if any of the arguments does not match its required type according to the function signature; or if a dynamic error occurs in evaluating the function.

callFunction

public void callFunction(QName function,
                         XdmValue[] arguments,
                         Destination destination)
                  throws SaxonApiException

Call a public user-defined function in the stylesheet, wrapping the result in an XML document, and sending this document to a specified destination

Parameters:

function - The name of the function to be called

arguments - The values of the arguments to be supplied to the function. These will be converted if necessary to the type as defined in the function signature, using the function conversion rules.

destination - the destination of the result document produced by wrapping the result of the apply-templates call in a document node.

Throws:

SaxonApiException - in the event of a dynamic error

Since:

9.6. Changed in 9.7.0.1 so that if a Serializer is supplied as the Destination, it will not be modified by this method to set output properties from the stylesheet; instead, the Serializer should be initialized by calling the newSerializer method on this Xslt30Transformer

asDocumentDestination

public Destination asDocumentDestination(Destination finalDestination)

Construct a Destination object whose effect is to perform this transformation on any input that is sent to that Destination: for example, it allows this transformation to post-process the results of another transformation.

This method allows a pipeline of transformations to be created in which one transformation is used as the destination of another. The transformations may use streaming, in which case intermediate results will not be materialized in memory. If a transformation does not use streaming, then its input will first be assembled in memory as a node tree.

The Destination returned by this method performs sequence normalization as defined in the serialization specification: that is, the raw result of the transformation sent to this destination is wrapped into a document node. Any item-separator present in any serialization parameters is ignored (adjacent atomic values are separated by whitespace). This makes the method unsuitable for passing intermediate results other than XML document nodes.

Returns:

a Destination which accepts an XML document (typically as a stream of events) and which transforms this supplied XML document (possibly using streaming) as defined by the stylesheet from which which this Xslt30Transformer was generated, sending the principal result of the transformation to the supplied finalDestination. The transformation is performed as if by the applyTemplates(Source, Destination) method: that is, by applying templates to the root node of the supplied XML document.

Since:

9.9

newSerializer

public Serializer newSerializer()

Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of Serializer.setOutputProperty(Serializer.Property, String).

Since:

9.7.0.1

newSerializer

public Serializer newSerializer(java.io.File file)

Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of Serializer.setOutputProperty(Serializer.Property, String).

Parameters:

file - the output file to which the serializer will write its output. As well as initializing the serializer to write to this output file, this method sets the base output URI of this Xslt30Transformer to be the URI of this file.

Since:

9.7.0.1

newSerializer

public Serializer newSerializer(java.io.Writer writer)

Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of Serializer.setOutputProperty(Serializer.Property, String).

Parameters:

writer - the Writer to which the serializer will write

Since:

9.7.0.1

newSerializer

public Serializer newSerializer(java.io.OutputStream stream)

Create a serializer initialised to use the default output parameters defined in the stylesheet. These serialization parameters can be overridden by use of Serializer.setOutputProperty(Serializer.Property, String).

Parameters:

stream - the output stream to which the serializer will write

Since:

9.7.0.1

setBaseOutputURI

public void setBaseOutputURI(java.lang.String uri)

Set the base output URI.

This defaults to the base URI of the Destination for the principal output of the transformation if a destination is supplied and its base URI is known.

If a base output URI is supplied using this method then it takes precedence over any base URI defined in the supplied Destination object, and it may cause the base URI of the Destination object to be modified in situ.

The base output URI is used for resolving relative URIs in the href attribute of the xsl:result-document instruction; it is accessible to XSLT stylesheet code using the XPath current-output-uri() function

Parameters:

uri - the base output URI

getBaseOutputURI

public java.lang.String getBaseOutputURI()

Get the base output URI.

This returns the value set using the setBaseOutputURI(java.lang.String) method. If no value has been set explicitly, then the method returns null if called before the transformation, or the computed default base output URI if called after the transformation.

The base output URI is used for resolving relative URIs in the href attribute of the xsl:result-document instruction.

Returns:

the base output URI

setURIResolver

public void setURIResolver(javax.xml.transform.URIResolver resolver)

Set an object that will be used to resolve URIs used in fn:doc() and related functions.

Parameters:

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

getURIResolver

public javax.xml.transform.URIResolver getURIResolver()

Get the URI resolver.

Returns:

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

setErrorListener

public void setErrorListener(javax.xml.transform.ErrorListener listener)

Set the ErrorListener to be used during this transformation

Parameters:

listener - The error listener to be used. This is notified of all dynamic errors detected during the transformation.

getErrorListener

public javax.xml.transform.ErrorListener getErrorListener()

Get the ErrorListener being used during this compilation episode

Returns:

listener The error listener in use. This is notified of all dynamic errors detected during the transformation. If no user-supplied ErrorListener has been set the method will return a system-supplied ErrorListener. If an explicit ErrorListener has been set using setErrorListener(ErrorListener), then that ErrorListener will generally be returned, unless the internal ErrorListener has been changed by some other mechanism.

setResultDocumentHandler

public void setResultDocumentHandler(java.util.function.Function<java.net.URI,Destination> handler)

Set a callback function that will be used when xsl:result-document is evaluated. The argument is a function that takes a URI as input (specifically, the value of the href argument to xsl:result-document, resolved against the base output URI of the transformation), and returns a Destination, which will be used as the destination for the result document.

If the href argument of the xsl:result-document instruction is absent or if it is set to a zero length string, then the callback function is not normally called; instead a Receiver for the secondary output is obtained by making a second call on Destination.getReceiver(PipelineConfiguration, SerializationProperties) for the principal destination of the transformation. In that situation, this result document handler is invoked only if the call on Destination.getReceiver(PipelineConfiguration, SerializationProperties) returns null.

If the base output URI is absent (perhaps because the principal output destination for the transformation was supplied as a OutputStream or Writer with no associated URI or systemId), then the value of the href attribute is used as is if it is an absolute URI; if it is a relative URI (including the case where it is absent or zero-length) then the callback function is not called; instead a dynamic error is raised (code SaxonErrorCode.SXRD0002).

If the callback function throws a SaxonApiUncheckedException, this will result in the xsl:result-document instruction failing with a dynamic error, which can be caught using xsl:try/xsl:catch. The error code, by default, will be "err:SXRD0001".

The application can request to be notified when the Destination is closed by setting a Destination.onClose(Action) callback on the Destination object.

Parameters:

handler - the callback function to be invoked whenever an xsl:result-document instruction is evaluated.

setMessageListener

public void setMessageListener(MessageListener listener)

Set the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction. If no MessageListener is nominated, the output of xsl:message instructions will be serialized and sent to the standard error stream.

Parameters:

listener - the MessageListener to be used

setMessageListener

public void setMessageListener(MessageListener2 listener)

Set the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction. If no MessageListener is nominated, the output of xsl:message instructions will be serialized and sent to the standard error stream.

The MessageListener2 interface differs from MessageListener in allowing the error code supplied to xsl:message to be notified.

Parameters:

listener - the MessageListener to be used

getMessageListener

public MessageListener getMessageListener()

Get the MessageListener to be notified whenever the stylesheet evaluates an xsl:message instruction. If no MessageListener has been nominated, return null

Returns:

the user-supplied MessageListener, or null if none has been supplied

getMessageListener2

public MessageListener2 getMessageListener2()

Get the MessageListener2 to be notified whenever the stylesheet evaluates an xsl:message instruction. If no MessageListener2 has been nominated, return null

Returns:

the user-supplied MessageListener2, or null if none has been supplied

setAssertionsEnabled

public void setAssertionsEnabled(boolean enabled)

Say whether assertions (xsl:assert instructions) should be 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

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

setTraceListener

public void setTraceListener(TraceListener listener)

Set a TraceListener to be notified of all events occurring during the transformation. This will only be effective if the stylesheet was compiled with trace code enabled (see XsltCompiler.setCompileWithTracing(boolean))

Parameters:

listener - the TraceListener to be used. Note that the TraceListener has access to interal Saxon interfaces which may vary from one release to the next. It is also possible that the TraceListener interface itself may be changed in future releases.

getTraceListener

public TraceListener getTraceListener()

Get the TraceListener to be notified of all events occurring during the transformation. If no TraceListener has been nominated, return null

Returns:

the user-supplied TraceListener, or null if none has been supplied

setTraceFunctionDestination

public void setTraceFunctionDestination(Logger stream)

Set the destination for output from the fn:trace() function. By default, the destination is System.err. If a TraceListener is in use, this is ignored, and the trace() output is sent to the TraceListener.

Parameters:

stream - the PrintStream to which trace output will be sent. If set to null, trace output is suppressed entirely. It is the caller's responsibility to close the stream after use.

getTraceFunctionDestination

public Logger getTraceFunctionDestination()

Get the destination for output from the fn:trace() function.

Returns:

the Logger to which trace output will be sent. If no explicitly destination has been set, returns System.err. If the destination has been set to null to suppress trace output, returns null.

applyTemplatesToSource

protected void applyTemplatesToSource(javax.xml.transform.Source source,
                                      Receiver out)
                               throws XPathException

Throws:

XPathException

isStreamableSource

protected boolean isStreamableSource(javax.xml.transform.Source source)

setSchemaValidationMode

public void setSchemaValidationMode(ValidationMode mode)

Set the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the doc(), document(), or collection() functions.

Parameters:

mode - the validation mode. Passing null causes no change to the existing value. Passing ValidationMode.DEFAULT resets to the initial value, which determines the validation requirements from the Saxon Configuration.

getSchemaValidationMode

public ValidationMode getSchemaValidationMode()

Get the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the doc(), document(), or collection() functions.

Returns:

the validation mode.

setInitialMode

public void setInitialMode(QName modeName)
                    throws java.lang.IllegalArgumentException

Set the initial mode for the transformation

Parameters:

modeName - the name of the initial mode. 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 default mode (which defaults to the unnamed mode, but can be set differently in an XSLT 3.0 stylesheet).

Throws:

java.lang.IllegalArgumentException - if the requested mode is not defined in the stylesheet

Since:

changed in 9.6 to throw an exception if the mode is not defined in the stylesheet. Chaned in 9.7 so that null means the default mode, not necessarily the unnamed mode.

getInitialMode

public QName getInitialMode()

Get the name of the initial mode for the transformation, if one has been set.

Returns:

the initial mode for the transformation. Returns null if no mode has been set, or if the mode was set to null to represent the default (unnamed) mode

getUnderlyingController

public XsltController getUnderlyingController()

Get the underlying Controller used to implement this XsltTransformer. This provides access to lower-level methods not otherwise available in the s9api interface. Note that classes and methods obtained by this route cannot be guaranteed stable from release to release.

Returns:

the underlying Controller

getDestinationReceiver

public Receiver getDestinationReceiver(XsltController controller,
                                       Destination destination)
                                throws SaxonApiException

Get a Receiver corresponding to the chosen Destination for the transformation

Parameters:

destination - the destination for the results of this transformation

Returns:

a receiver that sends the results to this destination

Throws:

SaxonApiException - if anything goes wrong

getReceivingTransformer

protected Receiver getReceivingTransformer(XsltController controller,
                                           GlobalParameterSet parameters,
                                           Destination finalDestination)
                                    throws SaxonApiException

Return a Receiver which can be used to supply the principal source document for the transformation. This method is intended primarily for internal use, though it can also be called by a user application that wishes to feed events into the transformation engine.

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.

Returns:

the Receiver to which events are to be sent.

Throws:

SaxonApiException - if the Receiver cannot be created

java.lang.IllegalStateException - if no Destination has been supplied