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

Since:
9.0

  • Constructor Details

    • XQueryCompiler

      protected XQueryCompiler(Processor processor)
      Protected constructor
      Parameters:
      processor - the Saxon Processor

  • Method Details

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

      This method is obsoleted by setErrorReporter(ErrorReporter), and its effect is to set an error reporter that delegates to the supplied ErrorListener.

      Parameters:
      listener - The error listener to be used. This is notified of all errors detected during the compilation. Static errors (as defined in the XQuery specification) are notified to the ErrorListener.fatalError(javax.xml.transform.TransformerException) method. Warnings are notified to the ErrorListener.warning(javax.xml.transform.TransformerException). Any exception thrown by these methods is ignored.

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

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

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

      If no error reporter is supplied by the caller, error information will be written to the standard error stream. Applications should then ensure that the contents of this stream are made visible to the query author.

      This error reporter is not used for dynamic errors occurring during query execution.

      Note that if multiple compilations are carried out concurrently in different threads using the same XQueryCompiler, 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 queries are known to be error-free.

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

    • getErrorReporter

      public ErrorReporter getErrorReporter()
      Get the recipient of error information previously registered using setErrorReporter(ErrorReporter).
      Returns:
      the recipient previously registered explicitly using setErrorReporter(ErrorReporter), or implicitly using setErrorListener(ErrorListener) or setErrorList(List). If no error reporter has been registered, the result may be null, or may return a system supplied error reporter.
      Since:
      10.0

    • 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.
      Throws:
      UnsupportedOperationException - if updating is requested and the Saxon Configuration does not support updating, either because it is not an EnterpriseConfiguration, or because no license key is available.
      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, then 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 query will be compiled with schema-awareness enabled even if it contains no "import schema" declarations. If false, the query is treated as schema-aware only if it contains one or more "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

    • setStreaming

      public void setStreaming(boolean option)
      Say whether the query should be compiled and evaluated to use streaming. This affects subsequent calls on the compile() methods. This option requires Saxon-EE.
      Parameters:
      option - if true, the compiler will attempt to compile a query to be capable of executing in streaming mode. If the query cannot be streamed, a compile-time exception is reported. In streaming mode, the source document is supplied as a stream, and no tree is built in memory. The default is false.

      When setStreaming(true) is specified, this has the additional side-effect of setting the required context item type to "document-node()"

      Since:
      9.6

    • isStreaming

      public boolean isStreaming()
      Ask whether the streaming option has been set, that is, whether subsequent calls on compile() will compile queries to be capable of executing in streaming mode.
      Returns:
      true if the streaming option has been set.
      Since:
      9.6

    • setLanguageVersion

      public void setLanguageVersion(String version)
      Say which version of XQuery should be used
      Parameters:
      version - "3.1" or "4.0" in the current Saxon release.

    • getLanguageVersion

      public String getLanguageVersion()
      Ask which version of XQuery is being used
      Returns:
      "3.1" or "4.0" in the current Saxon release.
      Since:
      9.2. From Saxon 9.8, only XQuery 3.1 was supported. From 11.0, XQuery 4.0 is supported

    • 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

    • getUnprefixedElementMatchingPolicy

      public UnprefixedElementMatchingPolicy getUnprefixedElementMatchingPolicy()
      Get the policy for handling of unprefixed element names in path expressions and match patterns.
      Returns:
      the policy previously set using setUnprefixedElementMatchingPolicy(UnprefixedElementMatchingPolicy), or its default, which is UnprefixedElementMatchingPolicy.DEFAULT_NAMESPACE.
      Since:
      12.3

    • 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. The default policy is UnprefixedElementMatchingPolicy.DEFAULT_NAMESPACE, which causes such names to be expanded using the default namespace for elements and types.

      Note that any setting other than the default causes the query to behave in a way that is not conformant with the W3C XQuery 3.1 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 query, 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 query, 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.

    • 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 Configuration.registerCollation(String, StringCollator), or it must be one that is recognized implicitly, such as a UCA collation
      Throws:
      NullPointerException - if the collation URI is null
      IllegalStateException - if the collation URI has not been registered, unless it is the standard Unicode codepoint collation which is registered implicitly
      Since:
      9.4

    • getDefaultCollationName

      public String getDefaultCollationName()
      Get the name of the default collation
      Returns:
      the name of the default collation for this query; or the name of the codepoint collation if no default collation has been defined.
      Since:
      11.0

    • 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

    • 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 expression is known to be correct, and (b) once compiled, the expression is only executed once against a document of modest size.

      The current implementation is equivalent to switching off all optimizations. 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
      Since:
      9.9

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

      If the query contains static errors, these will be notified to the registered ErrorListener. More than one static error may be reported. If any static errors have been reported, this method will exit with an exception, but the exception will only contain a summary message. The default ErrorListener writes details of each error to the System.err output stream.

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

    • setErrorList

      public void setErrorList(List<? super XmlProcessingError> errorList)
      List of errors. The caller should supply an empty list before calling Compile; the processor will then populate the list with error information obtained during the compilation. Each error will be included as an object of type XmlProcessingError.

      If no error list is supplied by the caller, error information will be written to the standard error stream. Applications should then ensure that the contents of this stream are made visible to the query author.

      By supplying a custom List with a user-written add() method, it is possible to intercept error conditions as they occur. Such a custom List can conveniently be implemented by extending AbstractList, in which case the only methods that need to be provided are java.util.AbstractList#get, java.util.AbstractList#size, and java.util.AbstractList#add; and the first two of these can be dummy implementations.

      Calling this method is equivalent to calling setErrorReporter(errorList::add): that is, it registers an ErrorReporter whose ErrorReporter.report(net.sf.saxon.s9api.XmlProcessingError) method adds the error to the list.

      Parameters:
      errorList - a (typically empty) list that will be populated with XmlProcessingError objects giving details of any static errors found in the query.
      Since:
      9.9. Redefined in 10.0 as a convenience wrapper over the new setErrorReporter(ErrorReporter) method.