Package net.sf.saxon.s9api

Class XsltCompiler

  • public class XsltCompiler
extends java.lang.Object
    An XsltCompiler object allows XSLT 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 stylesheets. Any changes made to the XsltCompiler (that is, to the static context) do not affect stylesheets 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 ErrorReporter 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 ErrorReporter 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 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

        @Deprecated
public void setURIResolver​(javax.xml.transform.URIResolver resolver)
        Deprecated.
        since 11.1. Use setResourceResolver(net.sf.saxon.lib.ResourceResolver)
        Set the URIResolver to be used during stylesheet compilation. This interface is retained for backwards compatibility reasons. The supplied URIResolver is wrapped in a ResourceResolver. The ResourceResolver interface is preferred because more information is made available; most obviously, the absolute URI formed by combining the base URI and relative URI.
        Parameters:
        resolver - the URIResolver to be used during stylesheet compilation.

      • setResourceResolver

        public void setResourceResolver​(ResourceResolver resolver)
        Set the ResourceResolver to be used during stylesheet compilation. The ResourceResolver is used for dereferencing an absolute URI (after URI resolution) to return a Source representing the location where a stylesheet module can be found.

        This ResourceResolver 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 ResourceResolver passed to the XsltTransformer or Xslt30Transformer).

        Parameters:
        resolver - the ResourceResolver 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

        @Deprecated
public javax.xml.transform.URIResolver getURIResolver()
        Deprecated.
        since 11.1 - use a ResourceResolver instead
        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.

      • getResourceResolver

        public ResourceResolver getResourceResolver()
        Get the ResourceResolver to be used during stylesheet compilation.
        Returns:
        the ResourceResolver used during stylesheet compilation. Returns null if no user-supplied ResourceResolver has been set.

      • setErrorListener

        @Deprecated
public void setErrorListener​(javax.xml.transform.ErrorListener listener)
        Deprecated.
        since 10.0. Use setErrorReporter(ErrorReporter)
        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.

        In earlier releases, contrary to the documentation, the supplied ErrorListener was also notified of run-time errors, unless a different ErrorListener was supplied at run-time. This is no longer the case from Saxon 10.0

      • getErrorListener

        @Deprecated
public javax.xml.transform.ErrorListener getErrorListener()
        Deprecated.
        since 10.0. Use getErrorReporter()
        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.

      • setErrorList

        public void setErrorList​(java.util.List<? super XmlProcessingError> 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 XmlProcessingError object.
        Since:
        9.9.

      • setErrorReporter

        public void setErrorReporter​(ErrorReporter reporter)
        Supply a callback which will be notified of all static errors and warnings encountered during a compilation carried out using this XsltCompiler.

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

        Note that if multiple compilations are carried out concurrently in different threads using the same XsltCompiler, then the ErrorReporter must be thread-safe; messages from different compilations will be interleaved, and there is no obvious way of determining which message originated from which compilation. In practice, it is only sensible to do this in an environment where the stylesheets being compiled are known to be error-free.

        Parameters:
        reporter - a class which will be notified of all static errors and warnings encountered during a compilation episode.
        Since:
        10.0

      • 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. By default 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.

        Setting the value to true has no effect (it is not an error) if the configuration does not support schema processing. (Schema processing requires a Saxon-EE license.)

        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", or "JS", "JS2", or "JS3".
        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", or "JS", "JS2", "JS3"
        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)
        Set the XSLT (and XPath) language level to be supported by the processor. Set the value to "4.0" to enable support for experimental features defined in the XSLT 4.0 proposal (which is likely to change before it stabilizes).
        Parameters:
        version - the language level to be supported. The values "3.0" and "4.0" are recognized
        Throws:
        java.lang.IllegalArgumentException - if the value is not equal to 3.0 or 4.0
        Since:
        9.3. From 11.0, accepts the values "3.0" and "4.0". From 12.2, also accepts "3" or "4".

      • getXsltLanguageVersion

        public java.lang.String getXsltLanguageVersion()
        Get the XSLT (and XPath) language level supported by the processor.
        Returns:
        the language level supported. In Saxon 11 this returns either "3.0" or "4.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

        Setting tracing to true suppresses those optimizations that cause major reorganisation of the code, such as function inlining and loop-lifting. These optimizations can be reinstated, but this will tend to make trace output harder to interpret.

        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

        @Deprecated
public void setGenerateByteCode​(boolean option)
        Deprecated.
        since 12.0 - the call has no effect.
        Set whether bytecode should be generated for the compiled stylesheet. This option has no effect from 12.0 (bytecode generation has been dropped from the product)
        Parameters:
        option - true if bytecode is to be generated, false otherwise
        Since:
        9.6.

      • isGenerateByteCode

        @Deprecated
public boolean isGenerateByteCode()
        Deprecated.
        since 12.0 - always returns false.
        Ask whether bytecode is to be generated in the compiled code. From 12.0 this always returns false.
        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 W3C specification) with the document specified in the source parameter, and that matches 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(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 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.

      • compilePackage

        public XsltPackage compilePackage​(java.io.File file)
                           throws SaxonApiException
        Compile a library package.

        This is a convenience method that simple calls compilePackage(new StreamSource(file)).

        Parameters:
        file - identifies an XML document holding 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:
        12.0
        See Also:
        - especially the notes regarding error handling and just-in-time compilation.

      • 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

      • loadLibraryPackage

        public XsltPackage loadLibraryPackage​(javax.xml.transform.Source input)
                               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:
        input - the source from which the package is to be loaded, as a JAXP Source object
        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:
        10.0

      • 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

      • loadExecutablePackage

        public XsltExecutable loadExecutablePackage​(javax.xml.transform.Source source)
                                     throws SaxonApiException
        Load a compiled package from a supplied source, with the intent to use this as a complete executable stylesheet, not as a library package.

        The supplied source 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:
        source - the source from which the package is to be loaded
        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:
        11

      • 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 - if an error is detected
        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.

      • compile

        public XsltExecutable compile​(java.io.File file)
                       throws SaxonApiException
        Compile a stylesheet held in a file.

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

        This is a convenience method that simply calls compile(new StreamSource(file)).

        Parameters:
        file - The file containing the principal stylesheet module to be compiled. Must not be null.
        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.
        Since:
        12.0

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

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

      • getDefaultElementNamespace

        public java.lang.String getDefaultElementNamespace()
        Get the value of the default namespace for elements and types
        Returns:
        the value that was set using the method setDefaultElementNamespace(String), if any; otherwise, the default value which is an empty string, representing "no namespace".

      • setDefaultElementNamespace

        public void setDefaultElementNamespace​(java.lang.String defaultNS)
        Set the value of the default namespace for elements and types
        Parameters:
        defaultNS - the value to be used as the default namespace for elements and types. This provides a default for the [xsl:]xpath-default-namespace attribute in the stylesheet, and it has no effect in any part of the stylesheet where an explicit value for [xsl:]xpath-default-namespace is in force. The default value is a zero-length string, representing "no namespace".

      • setUnprefixedElementMatchingPolicy

        public void setUnprefixedElementMatchingPolicy​(UnprefixedElementMatchingPolicy unprefixedElementMatchingPolicy)
        Set the policy for handling of unprefixed element names in path expressions and match patterns. By default, such names are expanded using the default namespace for elements and types, which can be set either using the [xsl:]default-xpath-namespace attribute in the stylesheet, or programmatically using the method setDefaultElementNamespace(String). The default policy is UnprefixedElementMatchingPolicy.DEFAULT_NAMESPACE, which causes such names to be expanded using the default namespace for elements and types, which itself defaults to "no namespace", but which can be changed either using the [xsl:]xpath-default-namespace attribute in the stylesheet, or using the setDefaultElementNamespace(String) method.

        Note that any setting other than the default causes the stylesheet to behave in a way that is not conformant with the W3C XSLT 3.0 specifications.

        The chosen policy affects:

        • Any NCName used as a node-test in an axis step (production ForwardStep or ReverseStep) in an XPath expression within the stylesheet, other than an axis step using the attribute or namespace axis
        • Any NCName used as a node-test in an axis step (production ForwardStepP in a pattern within the stylesheet, other than an axis step using the attribute or namespace axis

        It does not affect names appearing in other contexts (for example, names used in xsl:strip-space/@elements), and it does not affect name tests expressed in a form other than a simple NCName (for example tests of the form Q{}local, or *:local, or element(local)).

        It does not affect XPath expressions evaluated dynamically using xsl:evaluate.

        Parameters:
        unprefixedElementMatchingPolicy - the policy for handling unprefixed elements.