Package net.sf.saxon.s9api

## Class XPathCompiler

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

-     public class XPathCompiler
      extends java.lang.Object

  An `XPathCompiler` object allows XPath queries to be compiled. The compiler holds information that represents the static context for an XPath expression.

  To construct an `XPathCompiler`, use the factory method `Processor.newXPathCompiler()`.

  An `XPathCompiler` may be used repeatedly to compile multiple queries. Any changes made to the `XPathCompiler` (that is, to the static context) do not affect queries that have already been compiled. An `XPathCompiler` may be used concurrently in multiple threads, but it should not then be modified once initialized.

  Changes to an `XPathCompiler` are cumulative. There is no simple way to reset the `XPathCompiler` to its initial state; instead, simply create a new `XPathCompiler`.

  The `XPathCompiler` has the ability to maintain a cache of compiled expressions. This is active only if enabled by calling `setCaching(boolean)`. If caching is enabled, then the compiler will recognize an attempt to compile the same expression twice, and will avoid the cost of recompiling it. The cache is emptied by any method that changes the static context for subsequent expressions, for example, `setBaseURI(java.net.URI)`. Unless the cache is emptied, it grows indefinitely: compiled expressions are never discarded.

  Since:
    9.0

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `XPathCompiler​(Processor processor)` | Protected constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addXsltFunctionLibrary​(XsltPackage libraryPackage)` | Make available a set of functions defined in an XSLT 3.0 package.
    `XPathExecutable` | `compile​(java.lang.String source)` | Compile an XPath expression, supplied as a character string.
    `XPathExecutable` | `compilePattern​(java.lang.String source)` | Compile an XSLT 2.0 pattern, supplied as a character string.
    `void` | `declareDefaultCollation​(java.lang.String uri)` | Declare the default collation
    `void` | `declareNamespace​(java.lang.String prefix, java.lang.String uri)` | Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathCompiler
    `void` | `declareVariable​(QName qname)` | Declare a variable as part of the static context for XPath expressions compiled using this `XPathCompiler`.
    `void` | `declareVariable​(QName qname, ItemType itemType, OccurrenceIndicator occurrences)` | Declare a variable as part of the static context for XPath expressions compiled using this `XPathCompiler`.
    `XdmValue` | `evaluate​(java.lang.String expression, XdmItem contextItem)` | Compile and evaluate an XPath expression, supplied as a character string, with a given context item.
    `XdmItem` | `evaluateSingle​(java.lang.String expression, XdmItem contextItem)` | Compile and evaluate an XPath expression whose result is expected to be a single item, with a given context item.
    `java.net.URI` | `getBaseURI()` | Get the static base URI for XPath expressions compiled using this XPathCompiler.
    `java.lang.String` | `getLanguageVersion()` | Ask whether an XPath 2.0, XPath 3.0 or XPath 3.1 processor is being used
    `Processor` | `getProcessor()` | Get the Processor from which this XPathCompiler was constructed
    `ItemType` | `getRequiredContextItemType()` | Get the required type of the context item.
    `StaticContext` | `getUnderlyingStaticContext()` | Escape-hatch method to get the underlying static context object used by the implementation.
    `void` | `importSchemaNamespace​(java.lang.String uri)` | Import a schema namespace: that is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.
    `boolean` | `isAllowUndeclaredVariables()` | Ask whether undeclared variables are allowed.
    `boolean` | `isBackwardsCompatible()` | Ask whether XPath 1.0 backwards compatibility mode is in force.
    `boolean` | `isCaching()` | Ask whether the compiler is maintaining a cache of compiled expressions
    `boolean` | `isFastCompilation()` | Ask if fast compilation has been enabled.
    `boolean` | `isSchemaAware()` | Ask whether XPath expressions compiled using this XPathCompiler are schema-aware.
    `void` | `setAllowUndeclaredVariables​(boolean allow)` | Say whether undeclared variables are allowed.
    `void` | `setBackwardsCompatible​(boolean option)` | Say whether XPath 1.0 backwards compatibility mode is to be used.
    `void` | `setBaseURI​(java.net.URI uri)` | Set the static base URI for XPath expressions compiled using this XPathCompiler.
    `void` | `setCaching​(boolean caching)` | Say whether the compiler should maintain a cache of compiled expressions.
    `void` | `setDecimalFormatProperty​(QName format, java.lang.String property, java.lang.String value)` | Registers the required decimal format properties, for use in calls to the `fn:format-number()` function.
    `void` | `setFastCompilation​(boolean fast)` | Request fast compilation.
    `void` | `setLanguageVersion​(java.lang.String value)` | Say whether an XPath 2.0, XPath 3.0 or XPath 3.1 processor is required.
    `void` | `setRequiredContextItemType​(ItemType type)` | Declare the static type of the context item.
    `void` | `setSchemaAware​(boolean schemaAware)` | Say whether XPath expressions compiled using this `XPathCompiler` are schema-aware.
    `void` | `setWarningHandler​(ErrorReporter reporter)` | Set the error reporter to be used for reporting static warnings during compilation.

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

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

- - ### Constructor Detail

    - #### XPathCompiler

          protected XPathCompiler​(Processor processor)

      Protected constructor
      Parameters:
        `processor` - the s9api Processor

  - ### Method Detail

    - #### getProcessor

          public Processor getProcessor()

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

    - #### setBackwardsCompatible

          public void setBackwardsCompatible​(boolean option)

      Say whether XPath 1.0 backwards compatibility mode is to be used. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).
      Parameters:
        `option` - true if XPath 1.0 backwards compatibility is to be enabled, false if it is to be disabled.
      Since:
        9.1; changed in 9.8 to throw IllegalStateException if the feature is not available; change reverted by bug 3817.

    - #### isBackwardsCompatible

          public boolean isBackwardsCompatible()

      Ask whether XPath 1.0 backwards compatibility mode is in force.
      Returns:
        true if XPath 1.0 backwards compatibility is enabled, false if it is disabled.

    - #### setSchemaAware

          public void setSchemaAware​(boolean schemaAware)

      Say whether XPath expressions compiled using this `XPathCompiler` are schema-aware. They will automatically be schema-aware if the method `importSchemaNamespace(String)` is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.
      Parameters:
        `schemaAware` - true if expressions are to be schema-aware, false otherwise
      Throws:
        `java.lang.UnsupportedOperationException` - if schema-awareness is requested when this is not a licensed Saxon-EE configuration.
      Since:
        9.3. Changed in 9.9 to throw an exception if Saxon-EE is not available (previously, the option was either silently ignored, or caused a failure at some later time.)

    - #### isSchemaAware

          public boolean isSchemaAware()

      Ask whether XPath expressions compiled using this XPathCompiler are schema-aware. They will automatically be schema-aware if the method `importSchemaNamespace(String)` is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.
      Returns:
        true if expressions are to be schema-aware, false otherwise
      Since:
        9.3

    - #### setLanguageVersion

          public void setLanguageVersion​(java.lang.String value)

      Say whether an XPath 2.0, XPath 3.0 or XPath 3.1 processor is required.
      Parameters:
        `value` - One of the values 1.0, 2.0, 3.0, 3.05, 3.1.

        Setting the option to 1.0 requests an XPath 2.0 processor running in 1.0 compatibility mode; this is equivalent to setting the language version to 2.0 and backwards compatibility mode to true. Requesting "3.05" gives XPath 3.0 plus the extensions defined in the XSLT 3.0 specification (map types and map constructors).

      Throws:
        `java.lang.IllegalArgumentException` - if the version is not numerically equal to 1.0, 2.0, 3.0, 3.05, or 3.1.
      Since:
        9.3

    - #### getLanguageVersion

          public java.lang.String getLanguageVersion()

      Ask whether an XPath 2.0, XPath 3.0 or XPath 3.1 processor is being used
      Returns:
        version: "2.0", "3.0" or "3.1"
      Since:
        9.3

    - #### setBaseURI

          public void setBaseURI​(java.net.URI uri)

      Set the static base URI for XPath expressions compiled using this XPathCompiler. The base URI is part of the static context, and is used to resolve any relative URIs appearing within an XPath expression, for example a relative URI passed as an argument to the doc() function. If no static base URI is supplied, then the current working directory is used.
      Parameters:
        `uri` - the base URI to be set in the static context. This must be an absolute URI, or null to indicate that no static base URI is available.

    - #### getBaseURI

          public java.net.URI getBaseURI()

      Get the static base URI for XPath expressions compiled using this XPathCompiler. The base URI is part of the static context, and is used to resolve any relative URIs appearing within an XPath expression, for example a relative URI passed as an argument to the doc() function. If no static base URI has been explicitly set, this method returns null.
      Returns:
        the base URI from the static context

    - #### setWarningHandler

          public void setWarningHandler​(ErrorReporter reporter)

      Set the error reporter to be used for reporting static warnings during compilation. By default, the `ErrorReporter` associated with the Saxon Configuration is used.

      Note that fatal static errors are always reported in the form of an exception thrown by the `compile(String)` method, so this method only controls the handling of warnings

      Parameters:
        `reporter` - the ErrorReporter to which warnings will be notified
      Since:
        10.0

    - #### declareNamespace

          public void declareNamespace​(java.lang.String prefix,
                                       java.lang.String uri)

      Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathCompiler
      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:
        `java.lang.NullPointerException` - if either the prefix or uri is null.

    - #### importSchemaNamespace

          public void importSchemaNamespace​(java.lang.String uri)

      Import a schema namespace: that is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.

      This method will not cause the schema to be loaded. That must be done separately, using the `SchemaManager`. This method will not fail if the schema has not been loaded (but in that case the set of declarations and definitions made available to the XPath expression is empty). The schema document for the specified namespace may be loaded before or after this method is called.

      This method does not bind a prefix to the namespace. That must be done separately, using the `declareNamespace(String, String)` method.

      Parameters:
        `uri` - The schema namespace to be imported. To import declarations in a no-namespace schema, supply a zero-length string.
      Since:
        9.1

    - #### setAllowUndeclaredVariables

          public void setAllowUndeclaredVariables​(boolean allow)

      Say whether undeclared variables are allowed. By default, they are not allowed. When undeclared variables are allowed, it is not necessary to predeclare the variables that may be used in the XPath expression; instead, a variable is automatically declared when a reference to the variable is encountered within the expression.
      Parameters:
        `allow` - true if undeclared variables are allowed, false if they are not allowed.
      Since:
        9.2

    - #### isAllowUndeclaredVariables

          public boolean isAllowUndeclaredVariables()

      Ask whether undeclared variables are allowed. By default, they are not allowed. When undeclared variables are allowed, it is not necessary to predeclare the variables that may be used in the XPath expression; instead, a variable is automatically declared when a reference to the variable is encountered within the expression.
      Returns:
        true if undeclared variables are allowed, false if they are not allowed.
      Since:
        9.2

    - #### declareVariable

          public void declareVariable​(QName qname)

      Declare a variable as part of the static context for XPath expressions compiled using this `XPathCompiler`. It is an error for the XPath expression to refer to a variable unless it has been declared, unless the method `setAllowUndeclaredVariables(boolean)` has been called to permit undeclared variables. This method declares the existence of the variable, but it does not bind any value to the variable; that is done later, when the XPath expression is evaluated. The variable is allowed to have any type (that is, the required type is `item()*`).
      Parameters:
        `qname` - The name of the variable, expressions as a QName

    - #### declareVariable

          public void declareVariable​(QName qname,
                                      ItemType itemType,
                                      OccurrenceIndicator occurrences)

      Declare a variable as part of the static context for XPath expressions compiled using this `XPathCompiler`. It is an error for the XPath expression to refer to a variable unless it has been declared, unless the method `setAllowUndeclaredVariables(boolean)` has been called to permit undeclared variables. This method declares the existence of the variable, and defines the required type of the variable, but it does not bind any value to the variable; that is done later, when the XPath expression is evaluated.
      Parameters:
        `qname` - The name of the variable, expressed as a `QName`
        `itemType` - The required item type of the value of the variable, for example `ItemType.BOOLEAN`
        `occurrences` - The allowed number of items in the sequence forming the value of the variable

    - #### addXsltFunctionLibrary

          public void addXsltFunctionLibrary​(XsltPackage libraryPackage)

      Make available a set of functions defined in an XSLT 3.0 package. All functions defined with `visibility="public"` (or exposed as public using `xsl:expose` become part of the static context for an XPath expression created using this `XPathCompiler`. The functions are added to the search path after all existing functions, including functions added using a previous call on this method.

      Note that if the library package includes functions that reference stylesheet parameters (or global variables that depend on the context item), then there is no way of supplying values for such parameters; calling such functions will cause a run-time error.

      Parameters:
        `libraryPackage` - the XSLT compiled library package whose functions are to be made available
      Since:
        10.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, for example, `ItemType.ANY_NODE`.
      Since:
        9.3

    - #### 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 `ItemType.ANY_ITEM` (representing the type `item()`) is returned.
      Returns:
        the required type of the context item
      Since:
        9.3

    - #### declareDefaultCollation

          public void declareDefaultCollation​(java.lang.String uri)

      Declare the default collation
      Parameters:
        `uri` - the absolute URI of the default collation. This URI must identify a known collation; either one that has been explicitly declared, or one that is recognized implicitly, such as a UCA collation
      Throws:
        `java.lang.IllegalStateException` - if the collation URI is not recognized as a known collation
      Since:
        9.4

    - #### setCaching

          public void setCaching​(boolean caching)

      Say whether the compiler should maintain a cache of compiled expressions.
      Parameters:
        `caching` - if set to true, caching of compiled expressions is enabled. If set to false, any existing cache is cleared, and future compiled expressions will not be cached until caching is re-enabled. The cache is also cleared (but without disabling future caching) if any method is called that changes the static context for compiling expressions, for example `declareVariable(QName)` or `declareNamespace(String, String)`.
      Since:
        9.3

    - #### isCaching

          public boolean isCaching()

      Ask whether the compiler is maintaining a cache of compiled expressions
      Returns:
        true if a cache is being maintained
      Since:
        9.3

    - #### 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, it is only executed once against a document of modest size.
      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

    - #### compile

          public XPathExecutable compile​(java.lang.String source)
                                  throws SaxonApiException

      Compile an XPath expression, supplied as a character string.
      Parameters:
        `source` - A non-null string containing the source text of the XPath expression
      Returns:
        An XPathExecutable which represents the compiled xpath expression object. The XPathExecutable may be run as many times as required, in the same or a different thread. The XPathExecutable is not affected by any changes made to the XPathCompiler once it has been compiled.
      Throws:
        `SaxonApiException` - if any static error is detected while analyzing the expression.

        Note: prior to Saxon 9.7, static errors were also notified to the ErrorListener associated with the containing Processor/Configuration. This is no longer the case.

    - #### evaluate

          public XdmValue evaluate​(java.lang.String expression,
                                   XdmItem contextItem)
                            throws SaxonApiException

      Compile and evaluate an XPath expression, supplied as a character string, with a given context item.
      Parameters:
        `expression` - A non-null string containing the source text of the XPath expression
        `contextItem` - The context item to be used for evaluating the expression. This may be null if the expression is to be evaluated with no context item.
      Returns:
        the result of evaluating the XPath expression with this context item. Note that the result is an `Iterable`, so that it can be used in a "for-each" loop such as `for (XdmItem item : xpath.evaluate("//x", doc) {...}`
      Throws:
        `SaxonApiException` - if any static error is detected while analyzing the expression, or if any dynamic error is detected while evaluating it.
      Since:
        9.3

    - #### evaluateSingle

          public XdmItem evaluateSingle​(java.lang.String expression,
                                        XdmItem contextItem)
                                 throws SaxonApiException

      Compile and evaluate an XPath expression whose result is expected to be a single item, with a given context item. The expression is supplied as a character string.
      Parameters:
        `expression` - A non-null string containing the source text of the XPath expression
        `contextItem` - The context item to be used for evaluating the expression. This may be null if the expression is to be evaluated with no context item.
      Returns:
        the result of evaluating the XPath expression with this context item. If the result is a singleton it is returned as an XdmItem; if it is an empty sequence, the return value is null. If the expression returns a sequence of more than one item, any items after the first are ignored.
      Throws:
        `SaxonApiException` - if any static error is detected while analyzing the expression, or if any dynamic error is detected while evaluating it.
      Since:
        9.3

    - #### compilePattern

          public XPathExecutable compilePattern​(java.lang.String source)
                                         throws SaxonApiException

      Compile an XSLT 2.0 pattern, supplied as a character string. The compiled pattern behaves as a boolean expression which, when evaluated in a particular context, returns true if the context node matches the pattern, and false if it does not. An error is reported if there is no context item or it the context item is not a node.
      Parameters:
        `source` - A non-null string conforming to the syntax of XSLT 2.0 patterns
      Returns:
        An XPathExecutable representing an expression which evaluates to true when the context node matches the pattern, and false when it does not.
      Throws:
        `SaxonApiException` - if the pattern contains static errors: for example, if its syntax is incorrect, or if it refers to undeclared variables or namespaces
      Since:
        9.1

    - #### setDecimalFormatProperty

          public void setDecimalFormatProperty​(QName format,
                                               java.lang.String property,
                                               java.lang.String value)
                                        throws SaxonApiException

      Registers the required decimal format properties, for use in calls to the `fn:format-number()` function. The values for different properties may be supplied incrementally; they are only checked for consistency when an XPath expression is compiled.
      Parameters:
        `format` - The name of the decimal format. (Note: it is not possible to set properties for the default unnamed decimal format.)
        `property` - The decimal symbols name to update, for example `"grouping-separator"`
        `value` - The value to update the decimal symbol property
      Throws:
        `SaxonApiException` - if an invalid value is supplied for a decimal format property
        `java.lang.IllegalArgumentException` - if the value of {code property} is not one of the recognized decimal format properties
      Since:
        9.4

    - #### getUnderlyingStaticContext

          public StaticContext getUnderlyingStaticContext()

      Escape-hatch method to get the underlying static context object used by the implementation.
      Returns:
        the underlying static context object. In the current implementation this will always be an instance of `IndependentContext`.

        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.

      Since:
        9.1