net.sf.saxon.s9api

Class AbstractXsltTransformer

java.lang.Object

net.sf.saxon.s9api.AbstractXsltTransformer

Direct Known Subclasses:

Xslt30Transformer, XsltTransformer

public abstract class AbstractXsltTransformer
extends java.lang.Object

A class that exists to contain common code shared between XsltTransformer and Xslt30Transformer

Field Summary

Fields

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

Method Summary

Modifier and Type	Method and Description
protected void	applyTemplatesToSource(javax.xml.transform.Source source, Receiver out)
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 transformation
ErrorReporter	getErrorReporter() Get the callback that will be used when reporting a dynamic error or warning
QName	getInitialMode() Get the name of the initial mode for the transformation, if one has been set.
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.
ResourceResolver	getResourceResolver() Get the resource resolver.
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.
UnparsedTextURIResolver	getUnparsedTextURIResolver() Get the URI resolver used for fn:unparsed-text() and related functions.
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)
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	setErrorReporter(ErrorReporter reporter) Set a callback that will be used when reporting a dynamic error or warning.
void	setInitialMode(QName modeName) Set the initial mode for the transformation
void	setMessageHandler(java.util.function.Consumer<Message> messageHandler) Set a message handler to be notified of xsl:message and xsl:assert output.
void	setMessageListener(MessageListener2 listener) Set the MessageListener to be notified of xsl:message and xsl:assert output.
void	setResourceResolver(ResourceResolver resolver) Set the ResourceResolver to be used during stylesheet execution.
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.
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	setUnparsedTextResolver(UnparsedTextURIResolver resolver) Set an object that will be used to resolve URIs used in fn:unparsed-text() and related functions.
void	setURIResolver(javax.xml.transform.URIResolver resolver) Deprecated. since 11.1. Use setResourceResolver(net.sf.saxon.lib.ResourceResolver) in preference.

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

Method Detail

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)

Deprecated. since 11.1. Use setResourceResolver(net.sf.saxon.lib.ResourceResolver) in preference.

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

setResourceResolver

public void setResourceResolver(ResourceResolver resolver)

Set the ResourceResolver to be used during stylesheet execution. The ResourceResolver is used for dereferencing an absolute URI (after URI resolution) to return a Source representing the required resource.

This ResourceResolver is used to dereference the URIs appearing in the doc(), doc-available(), and document() functions: in these cases it may return any supported Source object.

It is also used to dereference the URI supplied to the xsl:source-document instruction. In this case the resource request passed to the resolver indicates whether the instruction has the attribute streamable="yes"; if it does, the returned Source object must be a StreamSource or SAXSource.

The resolver is also used for a number of other cases where URIs are dereferenced during stylesheet execution, for example in the fn:transform function

Parameters:

resolver - the ResourceResolver to be used during stylesheet execution.

getResourceResolver

public ResourceResolver getResourceResolver()

Get the resource resolver.

Returns:

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

setUnparsedTextResolver

public void setUnparsedTextResolver(UnparsedTextURIResolver resolver)

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

Parameters:

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

Since:

11

getUnparsedTextURIResolver

public UnparsedTextURIResolver getUnparsedTextURIResolver()

Get the URI resolver used for fn:unparsed-text() and related functions.

Returns:

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

Since:

11

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 transformation

Returns:

the error listener in use. If no user-supplied ErrorListener has been set the method will return a system-supplied ErrorListener that delegates to the ErrorReporter. 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.

setErrorReporter

public void setErrorReporter(ErrorReporter reporter)

Set a callback that will be used when reporting a dynamic error or warning. This is relevant primarily for non-fatal errors

Parameters:

reporter - the callback

getErrorReporter

public ErrorReporter getErrorReporter()

Get the callback that will be used when reporting a dynamic error or warning

Returns:

the callback

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(MessageListener2 listener)

Set the MessageListener to be notified of xsl:message and xsl:assert output.

Parameters:

listener - the MessageListener to be notified

setMessageHandler

public void setMessageHandler(java.util.function.Consumer<Message> messageHandler)

Set a message handler to be notified of xsl:message and xsl:assert output.

Parameters:

messageHandler - the message handler to be notified

Since:

11

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 SaxonApiException

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:

SaxonApiException - if the requested mode is not defined in the stylesheet, or if it is defined with visibility="private".

Since:

Changed in 9.6 to throw an exception if the mode is not defined in the stylesheet. Changed in 9.7 so that null means the default mode, not necessarily the unnamed mode. Changed in 11 to throw SaxonApiException rather than IllegalArgumentException, to prevent the error code being lost.

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:

controller - the Controller for the transformation

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.

Parameters:

controller - the Controller for the transformation

parameters - the global parameters

finalDestination - the destination for the results of this transformation

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