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 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
    --- | ---
    `XsltExecutable` | `compile(Source source)` Compile a stylesheet.
    `void` | `declareCollation(String uri, Collator collation)` Bind a collation URI to a collation
    `void` | `declareDefaultCollation(String uri)` Declare the default collation
    `ErrorListener` | `getErrorListener()` Get the ErrorListener being used during this compilation episode
    `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.
    `boolean` | `isCompileWithTracing()` Ask whether trace hooks are included in the compiled code.
    `boolean` | `isSchemaAware()` Ask whether schema-awareness has been requested by means of a call on `setSchemaAware(boolean)`
    `void` | `setCompileWithTracing(boolean option)` Set whether trace hooks are to be included in the compiled code.
    `void` | `setErrorListener(ErrorListener listener)` Set the ErrorListener to be used during this compilation episode
    `void` | `setParameter(QName name, XdmValue value)` Set the non-static paramters as well as static ones.
    `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 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 non-static paramters as well as static ones.
      Parameters:
        `name` - the StructuredQName of the parameter
        `value` - as a XdmValue of the parameter

    - #### 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)

      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)`
      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.

        The value 2.1 is accepted temporarily as a synonym for 3.0

      Throws:
        `IllegalArgumentException` - if the value is not numerically 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

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

    - #### 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 this object are not guaranteed stable from release to release.

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.