net.sf.saxon.s9api

Class XsltCompiler

java.lang.Object

net.sf.saxon.s9api.XsltCompiler

public class XsltCompiler
extends Object

An XsltCompiler object allows XSLT 2.0 and XSLT 3.0 stylesheets to be compiled. The compiler holds information that represents the static context for the compilation.

To construct an XsltCompiler, use the factory method Processor.newXsltCompiler() on the Processor object.

An XsltCompiler may be used repeatedly to compile multiple queries. Any changes made to the XsltCompiler (that is, to the static context) do not affect queries that have already been compiled. An XsltCompiler may be used concurrently in multiple threads, but it should not then be modified once initialized.

Since:

9.0

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XsltCompiler(Processor processor) Protected constructor.

Method Summary

Methods

Modifier and Type	Method and Description
Iterable<XsltPackage>	addCompilePackages(Iterable<Source> sources, boolean link) Add new packages to a package library.
void	clearParameters() Clear the values of all stylesheet parameters previously set using setParameter(QName, XdmValue).
XsltExecutable	compile(Source source) Compile a stylesheet.
XsltPackage	compilePackage(Source source) Compile a library package.
Iterable<XsltPackage>	compilePackages(Iterable<Source> sources) Compile a list of packages.
void	declareCollation(String uri, Collator collation) Deprecated. since 9.6. Collations are now held globally. If this method is called, the effect is to update the pool of collations held globally by the Processor.
void	declareDefaultCollation(String uri) Declare the default collation
Source	getAssociatedStylesheet(Source source, String media, String title, String charset) Get the stylesheet associated via the xml-stylesheet processing instruction (see http://www.w3.org/TR/xml-stylesheet/) with the document document specified in the source parameter, and that match the given criteria.
ErrorListener	getErrorListener() Get the ErrorListener being used during this compilation episode
PackageLibrary	getPackageLibrary()
Processor	getProcessor() Get the Processor from which this XsltCompiler was constructed
CompilerInfo	getUnderlyingCompilerInfo() Get the underlying CompilerInfo object, which provides more detailed (but less stable) control over some compilation options
URIResolver	getURIResolver() Get the URIResolver to be used during stylesheet compilation.
String	getXsltLanguageVersion() Get the XSLT (and XPath) language level supported by the processor.
void	importPackage(XsltPackage thePackage) Import a library package.
boolean	isAssertionsEnabled() Ask whether assertions (xsl:assert instructions) should be enabled.
boolean	isCompileWithTracing() Ask whether trace hooks are included in the compiled code.
boolean	isGenerateByteCode() Ask whether bytecode is to be generated in the compiled code.
boolean	isSchemaAware() Ask whether schema-awareness has been requested by means of a call on setSchemaAware(boolean)
XsltExecutable	loadExecutablePackage(URI location) Load a compiled package from a file or from a remote location, with the intent to use this as a complete executable stylesheet, not as a library package.
XsltPackage	loadLibraryPackage(URI location) Load a compiled package from a file or from a remote location.
void	newPackageLibrary() Initialise a fresh package library for this compiler This permits incremental additions to the library
void	setAssertionsEnabled(boolean enabled) Say whether assertions (xsl:assert instructions) should be enabled.
void	setCompileWithTracing(boolean option) Set whether trace hooks are to be included in the compiled code.
void	setErrorList(List<StaticError> errorList) Supply a List object which will be populated with information about any static errors encountered during the transformation.
void	setErrorListener(ErrorListener listener) Set the ErrorListener to be used during this compilation episode
void	setGenerateByteCode(boolean option) Set whether bytecode should be generated for the compiled stylesheet.
void	setPackageLibrary(PackageLibrary packageLibrary)
void	setParameter(QName name, XdmValue value) Set the value of a stylesheet parameter.
void	setSchemaAware(boolean schemaAware) Say that the stylesheet must be compiled to be schema-aware, even if it contains no xsl:import-schema declarations.
void	setURIResolver(URIResolver resolver) Set the URIResolver to be used during stylesheet compilation.
void	setXsltLanguageVersion(String version) Set the XSLT (and XPath) language level to be supported by the processor.

Methods inherited from class java.lang.Object

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

Constructor Detail

XsltCompiler

protected XsltCompiler(Processor processor)

Protected constructor. The public way to create an XsltCompiler is by using the factory method Processor.newXsltCompiler() .

Parameters:

processor - the Saxon processor

Method Detail

getProcessor

public Processor getProcessor()

Get the Processor from which this XsltCompiler was constructed

Returns:

the Processor to which this XsltCompiler belongs

Since:

9.3

setURIResolver

public void setURIResolver(URIResolver resolver)

Set the URIResolver to be used during stylesheet compilation. This URIResolver, despite its name, is not used for resolving relative URIs against a base URI; it is used for dereferencing an absolute URI (after resolution) to return a Source representing the location where a stylesheet module can be found.

This URIResolver is used to dereference the URIs appearing in xsl:import, xsl:include, and xsl:import-schema declarations. It is not used for resolving the URI supplied for the main stylesheet module (as supplied to the compile(javax.xml.transform.Source) or compilePackage(javax.xml.transform.Source) methods. It is not used at run-time for resolving requests to the document() or similar functions.

Parameters:

resolver - the URIResolver to be used during stylesheet compilation.

setParameter

public void setParameter(QName name,
                XdmValue value)

Set the value of a stylesheet parameter. Static (compile-time) parameters must be provided using this method on the XsltCompiler object, prior to stylesheet compilation. Non-static parameters may also be provided using this method if their values will not vary from one transformation to another.

Parameters:

name - the StructuredQName of the parameter

value - as a XdmValue of the parameter

clearParameters

public void clearParameters()

Clear the values of all stylesheet parameters previously set using setParameter(QName, XdmValue). This resets the parameters to their initial ("undeclared") state

getURIResolver

public URIResolver getURIResolver()

Get the URIResolver to be used during stylesheet compilation.

Returns:

the URIResolver used during stylesheet compilation. Returns null if no user-supplied URIResolver has been set.

setErrorListener

public void setErrorListener(ErrorListener listener)

Set the ErrorListener to be used during this compilation episode

Parameters:

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

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 errors detected during the compilation. Returns null if no user-supplied ErrorListener has been set.

setSchemaAware

public void setSchemaAware(boolean schemaAware)

Say that the stylesheet must be compiled to be schema-aware, even if it contains no xsl:import-schema declarations. Normally a stylesheet is treated as schema-aware only if it contains one or more xsl:import-schema declarations. If it is not schema-aware, then all input documents must be untyped, and validation of temporary trees is disallowed (though validation of the final result tree is permitted). Setting the argument to true means that schema-aware code will be compiled regardless.

Parameters:

schemaAware - If true, the stylesheet will be compiled with schema-awareness enabled even if it contains no xsl:import-schema declarations. If false, the stylesheet is treated as schema-aware only if it contains one or more xsl:import-schema declarations.

Since:

9.2

isSchemaAware

public boolean isSchemaAware()

Ask whether schema-awareness has been requested by means of a call on setSchemaAware(boolean)

Returns:

true if schema-awareness has been requested

Since:

9.2

declareCollation

public void declareCollation(String uri,
                    Collator collation)

Deprecated. since 9.6. Collations are now held globally. If this method is called, the effect is to update the pool of collations held globally by the Processor.

Bind a collation URI to a collation

Parameters:

uri - the absolute collation URI

collation - a Collator object that implements the required collation

Throws:

IllegalArgumentException - if an attempt is made to rebind the standard URI for the Unicode codepoint collation

Since:

9.5

declareDefaultCollation

public void declareDefaultCollation(String uri)

Declare the default collation

Parameters:

uri - the absolute URI of the default collation. This URI must have been bound to a collation using the method declareCollation(String, java.text.Collator), or it must be a collation that is recognized implicitly, such as a UCA collation

Throws:

IllegalStateException - if the collation URI has not been registered, unless it is the standard Unicode codepoint collation which is registered implicitly

Since:

9.5

setXsltLanguageVersion

public void setXsltLanguageVersion(String version)

Set the XSLT (and XPath) language level to be supported by the processor.

Parameters:

version - the language level to be supported. The value 2.0 requests a processor conforming to the XSLT 2.0 specification; 3.0 requests an XSLT 3.0 processor, while the value "0.0" (which is the default setting in the absence of a call on this method) gets a processor according to the value of the version attribute on the xsl:stylesheet element.

Although this interface can be used to run a 1.0 stylesheet, it is not possible to request a 1.0 processor; Saxon will handle it as a 2.0 processor in backwards-compatibility mode, which is not quite the same thing.

Note that Saxon-HE does not support XSLT 3.0. However, requesting 3.0 via this interface does not cause an error; an error only occurs if the stylesheet actually uses XSLT 3.0 features.

Throws:

IllegalArgumentException - if the value is not equal to 0.0, 2.0, or 3.0

Since:

9.3

getXsltLanguageVersion

public String getXsltLanguageVersion()

Get the XSLT (and XPath) language level supported by the processor.

Returns:

the language level supported. The value 2.0 represents a processor conforming to the XSLT 2.0 specification; 3.0 represents an XSLT 3.0 processor, while the value zero (which is the default setting in the absence of a call on setXsltLanguageVersion(java.lang.String) represents a processor selected according to the value of the version attribute on the xsl:stylesheet element.

Since:

9.3

isAssertionsEnabled

public boolean isAssertionsEnabled()

Ask whether assertions (xsl:assert instructions) should be enabled. By default they are disabled. 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

Returns:

true if assertions are enabled at compile time

Since:

9.7

setAssertionsEnabled

public void setAssertionsEnabled(boolean enabled)

Say whether assertions (xsl:assert instructions) should be enabled. By default they are disabled. 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

Parameters:

enabled - true if assertions are enabled at compile time

Since:

9.7

setCompileWithTracing

public void setCompileWithTracing(boolean option)

Set whether trace hooks are to be included in the compiled code. To use tracing, it is necessary both to compile the code with trace hooks included, and to supply a TraceListener at run-time

Parameters:

option - true if trace code is to be compiled in, false otherwise

Since:

9.3

isCompileWithTracing

public boolean isCompileWithTracing()

Ask whether trace hooks are included in the compiled code.

Returns:

true if trace hooks are included, false if not.

Since:

9.3

setGenerateByteCode

public void setGenerateByteCode(boolean option)

Set whether bytecode should be generated for the compiled stylesheet. This option is available only with Saxon-EE. The default depends on the setting in the configuration at the time the XsltCompiler is instantiated, and by default is true for Saxon-EE.

Parameters:

option - true if bytecode is to be generated, false otherwise

Since:

9.6

isGenerateByteCode

public boolean isGenerateByteCode()

Ask whether bytecode is to be generated in the compiled code.

Returns:

true if bytecode is to be generated, false if not.

Since:

9.6

getAssociatedStylesheet

public Source getAssociatedStylesheet(Source source,
                             String media,
                             String title,
                             String charset)
                               throws SaxonApiException

Get the stylesheet associated via the xml-stylesheet processing instruction (see http://www.w3.org/TR/xml-stylesheet/) with the document document specified in the source parameter, and that match the given criteria. If there are several suitable xml-stylesheet processing instructions, then the returned Source will identify a synthesized stylesheet module that imports all the referenced stylesheet module.

The returned Source will have an absolute URI, created by resolving any relative URI against the base URI of the supplied source document, and redirected if necessary by using the URIResolver associated with this XsltCompiler.

Parameters:

source - The XML source document. Note that if the source document is available as an instance of XdmNode, a corresponding Source can be obtained using the method XdmNode.asSource(). If the source is a StreamSource or SAXSource, it will be read only as far as the xml-stylesheet processing instruction (but the Source will be consumed and must not be re-used).

media - The media attribute to be matched. May be null, in which case the prefered templates will be used (i.e. alternate = no). Note that Saxon does not implement the complex CSS3-based syntax for media queries. By default, the media value is simply ignored. An algorithm for comparing the requested media with the declared media can be defined using the method Configuration.setMediaQueryEvaluator(Comparator).

title - The value of the title attribute to match. May be null.

charset - The value of the charset attribute to match. May be null.

Returns:

A Source object suitable for passing to compile(javax.xml.transform.Source).

Throws:

SaxonApiException - if any problems occur, including the case where no matching xml-stylesheet processing instruction is found.

Since:

9.6

compilePackage

public XsltPackage compilePackage(Source source)
                           throws SaxonApiException

Compile a library package.

The source argument identifies an XML file containing an <xsl:package> element. Any packages on which this package depends must have been made available to the XsltCompiler by importing them either using importPackage(net.sf.saxon.s9api.XsltPackage) or added previously through addCompilePackages(Iterable, boolean)}.

Parameters:

source - identifies an XML document holding the the XSLT package to be compiled

Returns:

the XsltPackage that results from the compilation. Note that this package is not automatically imported to this XsltCompiler; if the package is required for use in subsequent compilations then it must be explicitly imported.

Throws:

SaxonApiException - if the source cannot be read or if static errors are found during the compilation. Any such errors will have been notified to the registered ErrorListener if there is one, or reported on the System.err output stream otherwise.

Since:

9.6

newPackageLibrary

public void newPackageLibrary()

Initialise a fresh package library for this compiler This permits incremental additions to the library

getPackageLibrary

public PackageLibrary getPackageLibrary()

setPackageLibrary

public void setPackageLibrary(PackageLibrary packageLibrary)

compilePackages

public Iterable<XsltPackage> compilePackages(Iterable<Source> sources)
                                      throws SaxonApiException,
                                             XPathException

Compile a list of packages.

Parameters:

sources - the collection of packages to be compiled, in the form of an Iterable

Returns:

the collection of compiled packages, in the form of an Iterable.

Throws:

SaxonApiException - if the source cannot be read or if static errors are found during the compilation. Any such errors will have been notified to the registered ErrorListener if there is one, or reported on the System.err output stream otherwise.

XPathException

Since:

9.6

addCompilePackages

public Iterable<XsltPackage> addCompilePackages(Iterable<Source> sources,
                                       boolean link)
                                         throws SaxonApiException,
                                                XPathException

Add new packages to a package library. It assumes that a library (possibly empty) already exists in the compilerInfo and adds to anything there. In particular stylesheets can exploit packages that are already compiled and they can be linked during this process

Parameters:

sources - Sources for the packages

link - Link each of the packages when loaded if true

Returns:

the collection of compiled packages, in the form of an Iterable ..... note that unless link = true these will probably require link() processing before execution.

Throws:

SaxonApiException - if the source cannot be read or if static errors are found during the compilation. Any such errors will have been notified to the registered ErrorListener if there is one, or reported on the System.err output stream otherwise.

XPathException - if there are XPath errors in the stylesheet

loadLibraryPackage

public XsltPackage loadLibraryPackage(URI location)
                               throws SaxonApiException

Load a compiled package from a file or from a remote location.

The supplied URI represents the location of a resource which must have been originally created using XsltPackage.save(java.io.File).

The result of loading the package is returned as an XsltPackage object. Note that this package is not automatically imported to this XsltCompiler; if the package is required for use in subsequent compilations then it must be explicitly imported.

Parameters:

location - the location from which the package is to be loaded, as a URI

Returns:

the compiled package loaded from the supplied file or remote location

Throws:

SaxonApiException - if no resource can be loaded from the supplied location or if the resource that is loaded is not a compiled package, or if the compiled package is not consistent with this XsltCompiler (for example, if it was created using an incompatible Saxon version).

Since:

9.7

loadExecutablePackage

public XsltExecutable loadExecutablePackage(URI location)
                                     throws SaxonApiException

Load a compiled package from a file or from a remote location, with the intent to use this as a complete executable stylesheet, not as a library package.

The supplied URI represents the location of a resource which must have been originally created using XsltPackage.save(java.io.File).

The result of loading the package is returned as an XsltExecutable object.

Parameters:

location - the location from which the package is to be loaded, as a URI

Returns:

the compiled package loaded from the supplied file or remote location

Throws:

SaxonApiException - if no resource can be loaded from the supplied location or if the resource that is loaded is not a compiled package, or if the compiled package is not consistent with this XsltCompiler (for example, if it was created using an incompatible Saxon version).

Since:

9.7

importPackage

public void importPackage(XsltPackage thePackage)
                   throws SaxonApiException

Import a library package. Calling this method makes the supplied package available for reference in the xsl:use-package declaration of subsequent compilations performed using this XsltCompiler.

Parameters:

thePackage - the package to be imported

Throws:

SaxonApiException - if the imported package was created under a different Processor

Since:

9.6

compile

public XsltExecutable compile(Source source)
                       throws SaxonApiException

Compile a stylesheet.

Note: the term "compile" here indicates that the stylesheet is converted into an executable form. There is no implication that this involves code generation.

The source argument identifies the XML document holding the principal stylesheet module. Other modules will be located relative to this module by resolving against the base URI that is defined as the systemId property of the supplied Source.

The following kinds of Source are recognized:

• StreamSource, allowing the stylesheet to be supplied as a URI, as a File, as an InputStream, or as a Reader
• SAXSource, allowing the stylesheet to be supplied as a stream of SAX events from a SAX2-compliant XML parser (or any other source of SAX events)
• DOMSource, allowing the stylesheet to be supplied as a DOM tree. This option is available only if saxon9-dom.jar is on the classpath.
• Document wrappers for XOM, JDOM, or DOM4J trees, provided the appropriate support libraries are on the classpath
• A Saxon NodeInfo, representing the root of a tree in any of the native tree formats supported by Saxon
• An XdmNode representing the document node of the stylesheet module

Parameters:

source - Source object representing the principal stylesheet module to be compiled

Returns:

an XsltExecutable, which represents the compiled stylesheet.

Throws:

SaxonApiException - if the stylesheet contains static errors or if it cannot be read. Note that the exception that is thrown will not contain details of the actual errors found in the stylesheet. These will instead be notified to the registered ErrorListener. The default ErrorListener displays error messages on the standard error output.

getUnderlyingCompilerInfo

public CompilerInfo getUnderlyingCompilerInfo()

Get the underlying CompilerInfo object, which provides more detailed (but less stable) control over some compilation options

Returns:

the underlying CompilerInfo object, which holds compilation-time options. The methods on the CompilerInfo object are not guaranteed stable from release to release.

setErrorList

public void setErrorList(List<StaticError> errorList)

Supply a List object which will be populated with information about any static errors encountered during the transformation.

Parameters:

errorList - a List (typically empty) to which information will be appended about static errors found during the compilation. Each such error is represented by a StaticError object.