public class Xslt30Transformer
extends java.lang.Object
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
.
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:
xsl:with-param
on the implicit
apply-templates
call).xsl:with-param
on the implicit
call-template
instruction).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
.
Modifier | Constructor and Description |
---|---|
protected |
Xslt30Transformer(Processor processor,
Controller controller,
GlobalParameterSet staticParameters)
Protected constructor
|
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.
|
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.
|
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. |
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.
|
javax.xml.transform.URIResolver |
getURIResolver()
Get the URI resolver.
|
boolean |
isAssertionsEnabled()
Ask whether assertions (xsl:assert instructions) have been enabled at run time.
|
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)
Ask whether assertions (xsl:assert instructions) have been 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
|
void |
setInitialTemplateParameters(java.util.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 |
setMessageListener(MessageListener2 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(java.util.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(javax.xml.transform.URIResolver resolver)
Set an object that will be used to resolve URIs used in
fn:doc() and related functions.
|
protected Xslt30Transformer(Processor processor, Controller controller, GlobalParameterSet staticParameters)
processor
- the S9API processorcontroller
- the Saxon controller objectstaticParameters
- the static parameters supplied at stylesheet compile timepublic void setSchemaValidationMode(ValidationMode mode)
doc()
, document()
,
or collection()
functions.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.public ValidationMode getSchemaValidationMode()
doc()
, document()
,
or collection()
functions.public void setGlobalContextItem(XdmItem globalContextItem) throws SaxonApiException
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. It is more efficient to do this stripping while constructing the source tree.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.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.public void setGlobalContextItem(XdmItem globalContextItem, boolean alreadyStripped) throws SaxonApiException
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 placejava.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.public void setInitialContextNode(XdmNode node)
setGlobalContextItem(net.sf.saxon.s9api.XdmItem)
node
- the initial context node, or null if there is to be no initial context nodepublic void setInitialContextItem(XdmItem item)
setGlobalContextItem(net.sf.saxon.s9api.XdmItem)
item
- the initial context item, or null if there is to be no initial context itempublic void setStylesheetParameters(java.util.Map<QName,XdmValue> parameters) throws SaxonApiException
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.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.
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.public void setBaseOutputURI(java.lang.String 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.
uri
- the base output URIpublic java.lang.String getBaseOutputURI()
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.
public void setURIResolver(javax.xml.transform.URIResolver resolver)
resolver
- An object that implements the URIResolver interface, or
null.public javax.xml.transform.URIResolver getURIResolver()
public void setErrorListener(javax.xml.transform.ErrorListener listener)
listener
- The error listener to be used. This is notified of all dynamic errors detected during the
transformation.public javax.xml.transform.ErrorListener getErrorListener()
setErrorListener(ErrorListener)
,
then that ErrorListener will generally be returned, unless the internal ErrorListener has been changed
by some other mechanism.public void setMessageListener(MessageListener listener)
xsl:message
instruction. If no MessageListener is nominated,
the output of xsl:message
instructions will be serialized and sent
to the standard error stream.listener
- the MessageListener to be usedpublic void setMessageListener(MessageListener2 listener)
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.
listener
- the MessageListener to be usedpublic MessageListener getMessageListener()
xsl:message
instruction. If no MessageListener has been nominated,
return nullpublic boolean isAssertionsEnabled()
public void setAssertionsEnabled(boolean enabled)
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 timepublic void setTraceListener(TraceListener listener)
XsltCompiler.setCompileWithTracing(boolean)
)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.public TraceListener getTraceListener()
public void setTraceFunctionDestination(Logger stream)
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.public Logger getTraceFunctionDestination()
public void setInitialTemplateParameters(java.util.Map<QName,XdmValue> parameters, boolean tunnel) throws SaxonApiException
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
- the parameters to be used for the initial templatetunnel
- true if these values are to be used for setting tunnel parameters;
false if they are to be used for non-tunnel parametersSaxonApiException
- if running as an XSLT 2.0 processor, in which case initial template
parameters are not allowedpublic void setInitialMode(QName modeName) throws java.lang.IllegalArgumentException
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).java.lang.IllegalArgumentException
- if the requested mode is not defined in the stylesheetpublic QName getInitialMode()
public void applyTemplates(javax.xml.transform.Source source, Destination destination) throws SaxonApiException
setInitialMode(QName)
,
and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean)
.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).SaxonApiException
- if the transformation failspublic XdmValue applyTemplates(javax.xml.transform.Source source) throws SaxonApiException
XdmValue
. The invocation uses any initial mode set using setInitialMode(QName)
,
and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean)
.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
.
SaxonApiException
- if the transformation failspublic void applyTemplates(XdmValue selection, Destination destination) throws SaxonApiException
setInitialMode(QName)
,
and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean)
.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.SaxonApiException
- if the transformation failsnewSerializer
method on this Xslt30Transformer
public XdmValue applyTemplates(XdmValue selection) throws SaxonApiException
XdmValue
. The invocation uses any initial mode set using setInitialMode(QName)
,
and any template parameters set using setInitialTemplateParameters(java.util.Map, boolean)
.selection
- the initial value to which templates are to be applied (equivalent to the select
attribute of xsl:apply-templates
)SaxonApiException
- if the transformation failspublic void callTemplate(QName templateName, Destination destination) throws SaxonApiException
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).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. 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.SaxonApiException
- if there is no named template with this name, or if any dynamic
error occurs during the transformationnewSerializer
method on this Xslt30Transformer
public XdmValue callTemplate(QName templateName) throws SaxonApiException
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.SaxonApiException
- if there is no named template with this name, or if any dynamic
error occurs during the transformationpublic XdmValue callFunction(QName function, XdmValue[] arguments) throws SaxonApiException
function
- The name of the function to be calledarguments
- 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.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.public void callFunction(QName function, XdmValue[] arguments, Destination destination) throws SaxonApiException
function
- The name of the function to be calledarguments
- 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.SaxonApiException
- in the event of a dynamic errornewSerializer
method on this Xslt30Transformer
public Serializer newSerializer()
Serializer.setOutputProperty(Serializer.Property, String)
.public Serializer newSerializer(java.io.File file)
Serializer.setOutputProperty(Serializer.Property, String)
.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.public Serializer newSerializer(java.io.Writer writer)
Serializer.setOutputProperty(Serializer.Property, String)
.writer
- the Writer to which the serializer will writepublic Serializer newSerializer(java.io.OutputStream stream)
Serializer.setOutputProperty(Serializer.Property, String)
.stream
- the output stream to which the serializer will writepublic Controller getUnderlyingController()
Controller
Copyright (c) 2004-2018 Saxonica Limited. All rights reserved.