net.sf.saxon.s9api

Class Xslt30Transformer

java.lang.Object

net.sf.saxon.s9api.Xslt30Transformer

public class Xslt30Transformer
extends 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, 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.

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

Unlike XsltTransformer, an Xslt30Transformer is not a Destination. T 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

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
XdmValue	applyTemplates(Source source) Invoke the stylesheet by applying templates to a supplied Source document, returning the raw results as an XdmValue.
void	applyTemplates(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.
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.
String	getBaseOutputURI() Get the base output URI.
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.
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.
Controller	getUnderlyingController() Get the underlying Controller used to implement this XsltTransformer.
URIResolver	getURIResolver() Get the URI resolver.
boolean	isAssertionsEnabled() Ask whether assertions (xsl:assert instructions) have been enabled at run time.
void	setAssertionsEnabled(boolean enabled) Ask whether assertions (xsl:assert instructions) have been enabled at run time.
void	setBaseOutputURI(String uri) Set the base output URI.
void	setErrorListener(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	setInitialContextNode(XdmNode node) Set the initial context node for the transformation.
void	setInitialMode(QName modeName) Set the initial mode for the transformation
void	setInitialTemplateParameters(Map<QName,XdmValue> 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	setSchemaValidationMode(ValidationMode mode) Set the schema validation mode for the transformation.
void	setStylesheetParameters(Map<QName,XdmValue> parameters) Supply the values of global stylesheet variables and 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(URIResolver resolver) Set an object that will be used to resolve URIs used in fn:doc() and related functions.

Methods inherited from class java.lang.Object

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

Constructor Detail

Xslt30Transformer

protected Xslt30Transformer(Processor processor,
                 Controller 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

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.

setGlobalContextItem

public void setGlobalContextItem(XdmItem globalContextItem)
                          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.

Throws:

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.

setInitialContextNode

public void setInitialContextNode(XdmNode node)

Set the initial context node for the transformation.

This 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.

Parameters:

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

setStylesheetParameters

public void setStylesheetParameters(Map<QName,XdmValue> parameters)
                             throws SaxonApiException

Supply the values of global stylesheet variables and parameters.

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. If necessary the supplied values are converted to the declared type of the parameter. The contents of the supplied map are copied by this method, so subsequent changes to the map have no effect.

Throws:

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. Note that this method may detect any errors immediately, or may cause the errors to be reported later, when the value of the parameter is actually used.

setBaseOutputURI

public void setBaseOutputURI(String uri)

Set the base output URI.

This defaults to the system ID of the Destination for the principal output of the transformation if a destination is supplied and its System ID is known; in other cases, it defaults to the current directory.

If no base output URI is supplied, but the Destination of the transformation is a Serializer that writes to a file, then the URI of this file is used as the base output URI.

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

Parameters:

uri - the base output URI

getBaseOutputURI

public 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(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 URIResolver getURIResolver()

Get the URI resolver.

Returns:

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

setErrorListener

public void setErrorListener(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 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.

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

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

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

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.

setInitialTemplateParameters

public void setInitialTemplateParameters(Map<QName,XdmValue> 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 - if running as an XSLT 2.0 processor, in which case initial template parameters are not allowed

setInitialMode

public void setInitialMode(QName modeName)
                    throws 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:

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

applyTemplates

public void applyTemplates(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).

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 result document produced by wrapping the result of the apply-templates call in a document node. 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(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

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 of the result document produced by wrapping the result of the apply-templates call in a document node. 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(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 of the result document produced by wrapping the result of the apply-templates call in a document node. 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 there is no named template with this name, or if any dynamic error occurs during the transformation

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. 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 - in the event of a dynamic error

getUnderlyingController

public Controller 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