net.sf.saxon.s9api

Class XsltCompiler

java.lang.Object

net.sf.saxon.s9api.XsltCompiler

public class XsltCompiler
extends java.lang.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 in principle be used concurrently in multiple threads, but in practice this is best avoided because all instances will share the same ErrorListener and it may therefore be difficult to establish which error messages are associated with each compilation.

If JIT compilation is enabled (this is the default for Saxon-EE), then static errors in template rules might be detected not during execution of the compile() method, but rather when the relevant code is first executed. In this situation the compile() method will not throw an exception, but the errors will still (eventually) be notified to the ErrorListener associated with the compiler.

To avoid problems with error reporting, it is recommended that:

• When code is under development and static errors are therefore likely, a new XsltCompiler should be created for each compilation (and JIT should preferably be disabled, so that all static errors are detected.)
• When production code is being loaded, and errors are therefore unlikely, it is safe to use the same XsltCompiler for all compilations, and to enable JIT for maximum performance.

Since:

9.0

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
java.lang.Iterable<XsltPackage>	addCompilePackages(java.lang.Iterable<javax.xml.transform.Source> sources, boolean link) Deprecated. since 9.8. Multiple packages may be supplied in the form of a PackageLibrary registered with the underlying CompilerInfo, or may be listed in the configuration file. Alternatively they can be imported explicitly (taking care over the order of importing) using importPackage(XsltPackage).
void	clearParameters() Clear the values of all stylesheet parameters previously set using setParameter(QName, XdmValue).
XsltExecutable	compile(javax.xml.transform.Source source) Compile a stylesheet.
XsltPackage	compilePackage(javax.xml.transform.Source source) Compile a library package.
java.lang.Iterable<XsltPackage>	compilePackages(java.lang.Iterable<javax.xml.transform.Source> sources) Deprecated. since 9.8. Multiple packages may be supplied in the form of a PackageLibrary registered with the underlying CompilerInfo, or may be listed in the configuration file. Alternatively they can be imported explicitly (taking care over the order of importing) using importPackage(XsltPackage).
void	declareDefaultCollation(java.lang.String uri) Declare the default collation
javax.xml.transform.Source	getAssociatedStylesheet(javax.xml.transform.Source source, java.lang.String media, java.lang.String title, java.lang.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.
java.lang.String	getDefaultCollation() Get the default collation
javax.xml.transform.ErrorListener	getErrorListener() Get the ErrorListener being used during this compilation episode
Processor	getProcessor() Get the Processor from which this XsltCompiler was constructed
java.lang.String	getTargetEdition() Get the target edition under which the stylesheet will be executed.
CompilerInfo	getUnderlyingCompilerInfo() Get the underlying CompilerInfo object, which provides more detailed (but less stable) control over some compilation options
javax.xml.transform.URIResolver	getURIResolver() Get the URIResolver to be used during stylesheet compilation.
java.lang.String	getXsltLanguageVersion() Get the XSLT (and XPath) language level supported by the processor.
void	importPackage(XsltPackage thePackage) Import a library package.
void	importPackage(XsltPackage thePackage, java.lang.String packageName, java.lang.String version) Import a library package, changing the package name and/or version.
void	importXQueryEnvironment(XQueryCompiler queryCompiler) Import a compiled XQuery library.
boolean	isAssertionsEnabled() Ask whether assertions (xsl:assert instructions) should be enabled.
boolean	isCompileWithTracing() Ask whether trace hooks are included in the compiled code.
boolean	isFastCompilation() Ask if fast compilation has been enabled.
boolean	isGenerateByteCode() Ask whether bytecode is to be generated in the compiled code.
boolean	isJustInTimeCompilation() Ask whether just-in-time compilation of template rules should be used.
boolean	isRelocatable() Ask whether any package produced by this compiler can be deployed to a different location, with a different base URI
boolean	isSchemaAware() Ask whether schema-awareness has been requested by means of a call on setSchemaAware(boolean)
XsltExecutable	loadExecutablePackage(java.net.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(java.net.URI location) Load a compiled package from a file or from a remote location.
XsltPackage	obtainPackage(java.lang.String packageName, java.lang.String versionRange) Import a named package, together with all the packages on which it depends, recursively.
XsltPackage	obtainPackageWithAlias(java.lang.String alias) Import a package from the configuration file (or more generally, from the packageLibrary of this XsltCompiler) given an alias used to identify it
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(java.util.List<StaticError> errorList) Supply a (typically empty) List which will be populated with information about any static errors encountered during the transformation.
void	setErrorListener(javax.xml.transform.ErrorListener listener) Set the ErrorListener to be used during this compilation episode
void	setFastCompilation(boolean fast) Request fast compilation.
void	setGenerateByteCode(boolean option) Set whether bytecode should be generated for the compiled stylesheet.
void	setJustInTimeCompilation(boolean jit) Say whether just-in-time compilation of template rules should be used.
void	setParameter(QName name, XdmValue value) Set the value of a stylesheet parameter.
void	setRelocatable(boolean relocatable) Say whether any package produced by this compiler can be deployed to a different location, with a different base URI
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	setTargetEdition(java.lang.String edition) Set the target edition under which the stylesheet will be executed.
void	setURIResolver(javax.xml.transform.URIResolver resolver) Set the URIResolver to be used during stylesheet compilation.
void	setXsltLanguageVersion(java.lang.String version) Deprecated. Has no effect from Saxon 9.8.

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(javax.xml.transform.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. (Instead, such functions use the run-time URIResolver passed to the XsltTransformer or Xslt30Transformer).

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 qualified name identifying the parameter, as declared in a global <xsl:param> element in the stylesheet

value - the value of the parameter

Throws:

SaxonApiUncheckedException - if the value is lazily evaluated, and evaluation fails

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 javax.xml.transform.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(javax.xml.transform.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 javax.xml.transform.ErrorListener getErrorListener()

Get the ErrorListener being used during this compilation episode

Returns:

listener The error listener in use. This is notified of all 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

isRelocatable

public boolean isRelocatable()

Ask whether any package produced by this compiler can be deployed to a different location, with a different base URI

Returns:

if true then static-base-uri() represents the deployed location of the package, rather than its compile time location

Since:

9.8

setRelocatable

public void setRelocatable(boolean relocatable)

Say whether any package produced by this compiler can be deployed to a different location, with a different base URI

Parameters:

relocatable - if true then static-base-uri() represents the deployed location of the package, rather than its compile time location

Since:

9.8

setTargetEdition

public void setTargetEdition(java.lang.String edition)

Set the target edition under which the stylesheet will be executed.

Parameters:

edition - the Saxon edition for the run-time environment. One of "EE", "PE", "HE", "JS", or "JS2".

Since:

9.7.0.5. Experimental and subject to change.

getTargetEdition

public java.lang.String getTargetEdition()

Get the target edition under which the stylesheet will be executed.

Returns:

the Saxon edition for the run-time environment. One of "EE", "PE", "HE", "JS", or "JS2".

Since:

9.7.0.5. Experimental and subject to change.

declareDefaultCollation

public void declareDefaultCollation(java.lang.String uri)

Declare the default collation

Parameters:

uri - the absolute URI of the default collation. Either this URI must have been bound to a collation using the method Configuration.registerCollation(String, StringCollator), or it must be a collation that is recognized implicitly, such as a UCA collation

Throws:

java.lang.IllegalStateException - if the collation URI is not a recognized collation

Since:

9.5

getDefaultCollation

public java.lang.String getDefaultCollation()

Get the default collation

Returns:

the URI of the default collation if one has been set, or the URI of the codepoint collation otherwise

Since:

9.7.0.2

setXsltLanguageVersion

public void setXsltLanguageVersion(java.lang.String version)

Deprecated. Has no effect from Saxon 9.8.

Set the XSLT (and XPath) language level to be supported by the processor. This has no effect from Saxon 9.8: the processor is an XSLT 3.0 processor regardless of the language level requested.

Parameters:

version - the language level to be supported. The value is ignored.

Throws:

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

Since:

9.3. Has no effect from Saxon 9.8.

getXsltLanguageVersion

public java.lang.String getXsltLanguageVersion()

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

Returns:

the language level supported. From Saxon 9.8 this always returns "3.0".

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

setFastCompilation

public void setFastCompilation(boolean fast)

Request fast compilation. Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the stylesheet is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

Fast compilation may result in static errors going unreported, especially if they occur in code that is never executed.

The current implementation is equivalent to switching off all optimizations other than just-in-time compilation of template rules. Setting this option, however, indicates an intent rather than a mechanism, and the implementation details may change in future to reflect the intent.

Parameters:

fast - set to true to request fast compilation; set to false to revert to the optimization options defined in the Configuration.

Since:

9.9

isFastCompilation

public boolean isFastCompilation()

Ask if fast compilation has been enabled.

Returns:

true if fast compilation has been enabled (technically, this returns true if the only optimizer option that has been enabled is JIT compilation of template rules).

Since:

9.9

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

importXQueryEnvironment

public void importXQueryEnvironment(XQueryCompiler queryCompiler)

Import a compiled XQuery library. This makes pre-compiled XQuery library modules available to the saxon:import-query declaration.

Parameters:

queryCompiler - An XQueryCompiler that has been used to compile a library of XQuery functions (by using one of the overloaded methods named compileLibrary).

getAssociatedStylesheet

public javax.xml.transform.Source getAssociatedStylesheet(javax.xml.transform.Source source,
                                                          java.lang.String media,
                                                          java.lang.String title,
                                                          java.lang.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(javax.xml.transform.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 using importPackage(net.sf.saxon.s9api.XsltPackage).

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

See Also:

- especially the notes regarding error handling and just-in-time compilation.

compilePackages

public java.lang.Iterable<XsltPackage> compilePackages(java.lang.Iterable<javax.xml.transform.Source> sources)

Deprecated. since 9.8. Multiple packages may be supplied in the form of a PackageLibrary registered with the underlying CompilerInfo, or may be listed in the configuration file. Alternatively they can be imported explicitly (taking care over the order of importing) using importPackage(XsltPackage).

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:

java.lang.UnsupportedOperationException - - always. This method is no longer available from Saxon 9.8

Since:

9.6

addCompilePackages

public java.lang.Iterable<XsltPackage> addCompilePackages(java.lang.Iterable<javax.xml.transform.Source> sources,
                                                          boolean link)

Deprecated. since 9.8. Multiple packages may be supplied in the form of a PackageLibrary registered with the underlying CompilerInfo, or may be listed in the configuration file. Alternatively they can be imported explicitly (taking care over the order of importing) using importPackage(XsltPackage).

Add new packages to a package library.

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.

Since:

9.6

loadLibraryPackage

public XsltPackage loadLibraryPackage(java.net.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(java.net.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) or some equivalent.

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 declarations 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

importPackage

public void importPackage(XsltPackage thePackage,
                          java.lang.String packageName,
                          java.lang.String version)
                   throws SaxonApiException

Import a library package, changing the package name and/or version. Calling this method makes the supplied package available for reference in the xsl:use-package declaration of subsequent compilations performed using the XsltCompiler. The supplied package name and version are used in place of the name and version used in the XSLT source code. This provides a level of indirection: for example the same source package can be compiled twice, with different settings for the static parameter values, and the two different compiled versions can then be selected from xsl:use-package declarations. distinguishing them by the new package name and/or version.

Parameters:

thePackage - the package to be imported

packageName - the new package name to be used. If null, the original package name is used unchanged

version - the new package version number to be used. If null, the original package version number is used unchanged

Throws:

SaxonApiException - if the imported package was created under a different Processor, or if the supplied version number is invalid

Since:

9.8

obtainPackage

public XsltPackage obtainPackage(java.lang.String packageName,
                                 java.lang.String versionRange)
                          throws SaxonApiException

Import a named package, together with all the packages on which it depends, recursively. The package must be identified in the package library for this XsltCompiler, which defaults to the package library defined in the Configuration, typically set up by loading a configuration file.

Parameters:

packageName - the name of the required package. This is the name under which it is registered in the package library, which is not necessarily the same as the name appearing in the XSLT source code.

versionRange - the required version of the package, or range of versions, in the format of the package-version attribute of xsl:use-package.

Returns:

the best matching package if there is one, or null otherwise. The name of the package must match; if there are multiple versions, then the version chosen is based first on the priority attached to this package/version in the library, and if the priorities are equal (or there are no explicit priorities) then the one with highest version number is taken.

Throws:

SaxonApiException

Since:

9.8

obtainPackageWithAlias

public XsltPackage obtainPackageWithAlias(java.lang.String alias)
                                   throws SaxonApiException

Import a package from the configuration file (or more generally, from the packageLibrary of this XsltCompiler) given an alias used to identify it

Parameters:

alias - the alias of the package/version in the configuration file

Returns:

the referenced package

Throws:

SaxonApiException - the package does not exist, or if compiling the package fails

compile

public XsltExecutable compile(javax.xml.transform.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 relative URIs found in <xsl:include> and <xsl:import> declarations 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
• Document wrappers for XOM, JDOM, DOM4J, or AXIOM trees
• A Saxon NodeInfo, representing the root of a tree in any of the native tree formats supported by Saxon

The compilation uses a snapshot of the properties of the XsltCompiler at the time this method is invoked. This is relevant when JIT compilation is enabled (which is the default under Saxon-EE). Under JIT compilation, templates are compiled when first executed, which will typically be after the compile() method has returned. Subsequent changes to the properties of the XsltCompiler, for example, setting a new ErrorListener, have no effect on the delayed compilation of template rules at execution time.

If JIT compilation is enabled (this is the default for Saxon-EE), then static errors in template rules might be detected not during execution of the compile() method, but rather when the relevant code is first executed. In this situation the compile() method will not throw an exception, but the errors will still (eventually) be notified to the ErrorListener or ErrorList associated with the compiler: more specifically, the ErrorListener or ErrorList that was associated with the XsltCompiler at the time compile() was invoked.

Parameters:

source - Source object representing the principal stylesheet module to be compiled. Must not be null. If the Source wraps a resource such as a Reader or InputStream then the resource will be consumed by the method.

Returns:

an XsltExecutable, which represents the compiled stylesheet. The XsltExecutable is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently.

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 or ErrorList. 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(java.util.List<StaticError> errorList)

Supply a (typically empty) List which will be populated with information about any static errors encountered during the transformation.

Calling this method overwrites the effect of any previous call on setErrorListener(ErrorListener) as well as previous calls on setErrorList.

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.

Since:

9.9

setJustInTimeCompilation

public void setJustInTimeCompilation(boolean jit)

Say whether just-in-time compilation of template rules should be used.

Parameters:

jit - true if just-in-time compilation is to be enabled. With this option enabled, static analysis of a template rule is deferred until the first time that the template is matched. This can improve performance when many template rules are rarely used during the course of a particular transformation; however, it means that static errors in the stylesheet will not necessarily cause the compile(Source) method to throw an exception (errors in code that is actually executed will still be notified to the registered ErrorListener or ErrorList, but this may happen after the compile(Source) method returns). This option is enabled by default in Saxon-EE, and is not available in Saxon-HE or Saxon-PE.

Recommendation: disable this option unless you are confident that the stylesheet you are compiling is error-free.

Throws:

java.lang.UnsupportedOperationException - if the argument is set to true and the configuration is not a licensed Saxon-EE configuration.

isJustInTimeCompilation

public boolean isJustInTimeCompilation()

Ask whether just-in-time compilation of template rules should be used.

Returns:

true if just-in-time compilation is enabled. With this option enabled, static analysis of a template rule is deferred until the first time that the template is matched. This can improve performance when many template rules are rarely used during the course of a particular transformation; however, it means that static errors in the stylesheet may go undetected.