net.sf.saxon.s9api

## Class XQueryCompiler

- java.lang.Object
- - net.sf.saxon.s9api.XQueryCompiler

-     public class XQueryCompiler
      extends Object

  An XQueryCompiler object allows XQuery 1.0 queries to be compiled. The compiler holds information that represents the static context for the compilation.

  To construct an XQueryCompiler, use the factory method `Processor.newXQueryCompiler()`.

  An XQueryCompiler may be used repeatedly to compile multiple queries. Any changes made to the XQueryCompiler (that is, to the static context) do not affect queries that have already been compiled. An XQueryCompiler 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` | `XQueryCompiler(Processor processor)` Protected constructor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `XQueryExecutable` | `compile(File query)` Compile a query supplied as a file
    `XQueryExecutable` | `compile(InputStream query)` Compile a query supplied as an InputStream
    `XQueryExecutable` | `compile(Reader query)` Compile a query supplied as a Reader
    `XQueryExecutable` | `compile(String query)` Compile a query supplied as a string.
    `void` | `compileLibrary(File query)` Compile a library module supplied as a file.
    `void` | `compileLibrary(InputStream query)` Compile a library module supplied as an InputStream.
    `void` | `compileLibrary(Reader query)` Compile a library module supplied as a Reader.
    `void` | `compileLibrary(String query)` Compile a library module supplied as a string.
    `void` | `declareCollation(String uri, Collator collation)` Bind a collation URI to a collation
    `void` | `declareDefaultCollation(String uri)` Declare the default collation
    `void` | `declareNamespace(String prefix, String uri)` Declare a namespace binding as part of the static context for queries compiled using this XQueryCompiler.
    `URI` | `getBaseURI()` Get the static base URI for the query
    `String` | `getEncoding()` Get the encoding previously set for the supplied query.
    `ErrorListener` | `getErrorListener()` Get the ErrorListener being used during this compilation episode
    `String` | `getLanguageVersion()` Ask whether an XQuery 1.0 or XQuery 1.1 processor is being used
    `ModuleURIResolver` | `getModuleURIResolver()` Get the user-defined ModuleURIResolver for resolving URIs used in `import module` declarations in the XQuery prolog; returns null if none has been explicitly set either here or in the Saxon Configuration.
    `Processor` | `getProcessor()` Get the Processor from which this XQueryCompiler was constructed
    `ItemType` | `getRequiredContextItemType()` Get the required type of the context item.
    `StaticQueryContext` | `getUnderlyingStaticContext()` Get the underlying `StaticQueryContext` object that maintains the static context information on behalf of this XQueryCompiler.
    `boolean` | `isCompileWithTracing()` Ask whether trace hooks are included in the compiled code.
    `boolean` | `isSchemaAware()` Ask whether schema-awareness has been requested either by means of a call on `setSchemaAware(boolean)`
    `boolean` | `isUpdatingEnabled()` Ask whether the query is allowed to use XQuery Update syntax
    `void` | `setBaseURI(URI baseURI)` Set the static base URI for the query
    `void` | `setCompileWithTracing(boolean option)` Set whether trace hooks are to be included in the compiled code.
    `void` | `setEncoding(String encoding)` Set the encoding of the supplied query.
    `void` | `setErrorListener(ErrorListener listener)` Set the ErrorListener to be used during this query compilation episode
    `void` | `setLanguageVersion(String version)` Say whether an XQuery 1.0 or XQuery 3.0 processor is required.
    `void` | `setModuleURIResolver(ModuleURIResolver resolver)` Set a user-defined ModuleURIResolver for resolving URIs used in `import module` declarations in the XQuery prolog.
    `void` | `setRequiredContextItemType(ItemType type)` Declare the static type of the context item.
    `void` | `setSchemaAware(boolean schemaAware)` Say that the query must be compiled to be schema-aware, even if it contains no "import schema" declarations.
    `void` | `setUpdatingEnabled(boolean updating)` Say whether the query is allowed to be updating.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### XQueryCompiler

          protected XQueryCompiler(Processor processor)

      Protected constructor
      Parameters:
        `processor` - the Saxon Processor

  - ### Method Detail

    - #### getProcessor

          public Processor getProcessor()

      Get the Processor from which this XQueryCompiler was constructed
      Returns:
        the Processor to which this XQueryCompiler belongs
      Since:
        9.3

    - #### setBaseURI

          public void setBaseURI(URI baseURI)

      Set the static base URI for the query
      Parameters:
        `baseURI` - the static base URI; or null to indicate that no base URI is available

    - #### getBaseURI

          public URI getBaseURI()

      Get the static base URI for the query
      Returns:
        the static base URI

    - #### setErrorListener

          public void setErrorListener(ErrorListener listener)

      Set the ErrorListener to be used during this query 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. If no user-supplied ErrorListener has been set, returns the system-supplied ErrorListener.

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

    - #### isCompileWithTracing

          public boolean isCompileWithTracing()

      Ask whether trace hooks are included in the compiled code.
      Returns:
        true if trace hooks are included, false if not.

    - #### setModuleURIResolver

          public void setModuleURIResolver(ModuleURIResolver resolver)

      Set a user-defined ModuleURIResolver for resolving URIs used in `import module` declarations in the XQuery prolog. This will override any ModuleURIResolver that was specified as part of the configuration.
      Parameters:
        `resolver` - the ModuleURIResolver to be used

    - #### getModuleURIResolver

          public ModuleURIResolver getModuleURIResolver()

      Get the user-defined ModuleURIResolver for resolving URIs used in `import module` declarations in the XQuery prolog; returns null if none has been explicitly set either here or in the Saxon Configuration.
      Returns:
        the registered ModuleURIResolver

    - #### setEncoding

          public void setEncoding(String encoding)

      Set the encoding of the supplied query. This is ignored if the query is supplied in character form, that is, as a `String` or as a `Reader`. If no value is set, the query processor will attempt to infer the encoding, defaulting to UTF-8 if no information is available.
      Parameters:
        `encoding` - the encoding of the supplied query, for example "iso-8859-1"
      Since:
        9.1

    - #### getEncoding

          public String getEncoding()

      Get the encoding previously set for the supplied query.
      Returns:
        the encoding previously set using `setEncoding(String)`, or null if no value has been set. Note that this is not necessarily the actual encoding of the query.
      Since:
        9.2

    - #### setUpdatingEnabled

          public void setUpdatingEnabled(boolean updating)

      Say whether the query is allowed to be updating. XQuery update syntax will be rejected during query compilation unless this flag is set. XQuery Update is supported only under Saxon-EE.
      Parameters:
        `updating` - true if the query is allowed to use the XQuery Update facility (requires Saxon-EE). If set to false, the query must not be an updating query. If set to true, it may be either an updating or a non-updating query.
      Since:
        9.1

    - #### isUpdatingEnabled

          public boolean isUpdatingEnabled()

      Ask whether the query is allowed to use XQuery Update syntax
      Returns:
        true if the query is allowed to use the XQuery Update facility. Note that this does not necessarily mean that the query is an updating query; but if the value is false, the it must definitely be non-updating.
      Since:
        9.1

    - #### setSchemaAware

          public void setSchemaAware(boolean schemaAware)

      Say that the query must be compiled to be schema-aware, even if it contains no "import schema" declarations. Normally a query is treated as schema-aware only if it contains one or more "import schema" declarations. If it is not schema-aware, then all input documents must be untyped (or xs:anyType), and validation of temporary nodes 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. Note that setting the value to false does not disable use of an import-schema declaration.
      Since:
        9.2

    - #### isSchemaAware

          public boolean isSchemaAware()

      Ask whether schema-awareness has been requested either by means of a call on `setSchemaAware(boolean)`
      Returns:
        true if schema-awareness has been requested
      Since:
        9.2

    - #### setLanguageVersion

          public void setLanguageVersion(String version)

      Say whether an XQuery 1.0 or XQuery 3.0 processor is required.
      Parameters:
        `version` - Must be "1.0" or "3.0". At present onle limited support for XQuery 3.01 is available. This functionality is available only in Saxon-EE, and it cannot be used in conjunction with XQuery Updates. To use XQuery 3.0 features, the query prolog must also specify version="3.0".

        In Saxon 9.3, the value "1.1" is accepted as a synonym for "3.0".

      Throws:
        `IllegalArgumentException` - if the version is not 1.0 or 3.0.
      Since:
        9.2

    - #### getLanguageVersion

          public String getLanguageVersion()

      Ask whether an XQuery 1.0 or XQuery 1.1 processor is being used
      Returns:
        version: "1.0" or "3.0"
      Since:
        9.2

    - #### declareNamespace

          public void declareNamespace(String prefix,
                              String uri)

      Declare a namespace binding as part of the static context for queries compiled using this XQueryCompiler. This binding may be overridden by a binding that appears in the query prolog. The namespace binding will form part of the static context of the query, but it will not be copied into result trees unless the prefix is actually used in an element or attribute name.
      Parameters:
        `prefix` - The namespace prefix. If the value is a zero-length string, this method sets the default namespace for elements and types.
        `uri` - The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace; in this case the prefix will not be available for use, except in the case where the prefix is also a zero length string, in which case the absence of a prefix implies that the name is in no namespace.
      Throws:
        `NullPointerException` - if either the prefix or uri is null.
        `IllegalArgumentException` - in the event of an invalid declaration of the XML namespace

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

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

    - #### setRequiredContextItemType

          public void setRequiredContextItemType(ItemType type)

      Declare the static type of the context item. If this type is declared, and if a context item is supplied when the query is invoked, then the context item must conform to this type (no type conversion will take place to force it into this type).
      Parameters:
        `type` - the required type of the context item

    - #### getRequiredContextItemType

          public ItemType getRequiredContextItemType()

      Get the required type of the context item. If no type has been explicitly declared for the context item, an instance of AnyItemType (representing the type item()) is returned.
      Returns:
        the required type of the context item

    - #### compileLibrary

          public void compileLibrary(String query)
                              throws SaxonApiException

      Compile a library module supplied as a string. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

      The base URI of the query should be supplied by calling `setBaseURI(java.net.URI)`

      Separate compilation of library modules is supported only under Saxon-EE

      Parameters:
        `query` - the text of the query
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
      Since:
        9.2

    - #### compileLibrary

          public void compileLibrary(File query)
                              throws SaxonApiException,
                                     IOException

      Compile a library module supplied as a file. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

      The encoding of the input stream may be specified using `setEncoding(String)`; if this has not been set, the compiler determines the encoding from the version header of the query, and if that too is absent, it assumes UTF-8.

      Separate compilation of library modules is supported only under Saxon-EE

      Parameters:
        `query` - the file containing the query. The URI corresponding to this file will be used as the base URI of the query, overriding any URI supplied using `setBaseURI(java.net.URI)` (but not overriding any base URI specified within the query prolog)
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
        `IOException` - if the file does not exist or cannot be read
      Since:
        9.2

    - #### compileLibrary

          public void compileLibrary(Reader query)
                              throws SaxonApiException

      Compile a library module supplied as a Reader. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

      The base URI of the query should be supplied by calling `setBaseURI(java.net.URI)`

      Separate compilation of library modules is supported only under Saxon-EE

      Parameters:
        `query` - the text of the query
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
      Since:
        9.2

    - #### compileLibrary

          public void compileLibrary(InputStream query)
                              throws SaxonApiException

      Compile a library module supplied as an InputStream. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

      The encoding of the input stream may be specified using `setEncoding(String)`; if this has not been set, the compiler determines the encoding from the version header of the query, and if that too is absent, it assumes UTF-8.

      The base URI of the query should be supplied by calling `setBaseURI(java.net.URI)`

      Separate compilation of library modules is supported only under Saxon-EE

      Parameters:
        `query` - the text of the query
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
      Since:
        9.2

    - #### compile

          public XQueryExecutable compile(String query)
                                   throws SaxonApiException

      Compile a query supplied as a string.

      The base URI of the query should be supplied by calling `setBaseURI(java.net.URI)`

      Parameters:
        `query` - the text of the query
      Returns:
        an XQueryExecutable representing the compiled query
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
      Since:
        9.0

    - #### compile

          public XQueryExecutable compile(File query)
                                   throws SaxonApiException,
                                          IOException

      Compile a query supplied as a file
      Parameters:
        `query` - the file containing the query. The URI corresponding to this file will be used as the base URI of the query, overriding any URI supplied using `setBaseURI(java.net.URI)` (but not overriding any base URI specified within the query prolog)
      Returns:
        an XQueryExecutable representing the compiled query
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
        `IOException` - if the file does not exist or cannot be read
      Since:
        9.1

    - #### compile

          public XQueryExecutable compile(InputStream query)
                                   throws SaxonApiException,
                                          IOException

      Compile a query supplied as an InputStream

      The base URI of the query should be supplied by calling `setBaseURI(java.net.URI)`

      Parameters:
        `query` - the input stream on which the query is supplied. This will be consumed by this method
      Returns:
        an XQueryExecutable representing the compiled query
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
        `IOException` - if the file does not exist or cannot be read
      Since:
        9.1

    - #### compile

          public XQueryExecutable compile(Reader query)
                                   throws SaxonApiException,
                                          IOException

      Compile a query supplied as a Reader

      The base URI of the query should be supplied by calling `setBaseURI(java.net.URI)`

      Parameters:
        `query` - the input stream on which the query is supplied. This will be consumed by this method
      Returns:
        an XQueryExecutable representing the compiled query
      Throws:
        `SaxonApiException` - if the query compilation fails with a static error
        `IOException` - if the file does not exist or cannot be read
      Since:
        9.1

    - #### getUnderlyingStaticContext

          public StaticQueryContext getUnderlyingStaticContext()

      Get the underlying `StaticQueryContext` object that maintains the static context information on behalf of this XQueryCompiler. This method provides an escape hatch to internal Saxon implementation objects that offer a finer and lower-level degree of control than the s9api classes and methods. Some of these classes and methods may change from release to release.
      Returns:
        the underlying StaticQueryContext object
      Since:
        9.2

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