Package net.sf.saxon.s9api

## Class XPathExecutable

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

-     public class XPathExecutable
      extends java.lang.Object

  An XPathExecutable represents the compiled form of an XPath expression. To evaluate the expression, it must first be loaded to form an `XPathSelector`.

  An XPathExecutable is immutable, and therefore thread-safe. It is simplest to load a new XPathSelector each time the expression is to be evaluated. However, the XPathSelector is serially reusable within a single thread.

  An XPathExecutable is created by using the `XPathCompiler.compile(java.lang.String)` method on the `XPathCompiler` class.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `XPathExecutable​(XPathExpression exp, Processor processor, IndependentContext env)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Step<XdmItem>` | `asStep()` | Treat the compiled XPath expression as a `Step`, so that it can be used in a call on `XdmValue.select(net.sf.saxon.s9api.streams.Step<T>)`.
    `OccurrenceIndicator` | `getRequiredCardinalityForVariable​(QName variableName)` | Get the required cardinality of a declared variable in the static context of the expression.
    `ItemType` | `getRequiredItemTypeForVariable​(QName variableName)` | Get the required item type of a declared variable in the static context of the expression.
    `OccurrenceIndicator` | `getResultCardinality()` | Get the statically-determined cardinality of the result of the expression.
    `ItemType` | `getResultItemType()` | Get the ItemType of the items in the result of the expression, as determined by static analysis.
    `XPathExpression` | `getUnderlyingExpression()` | Get the underlying implementation object representing the compiled XPath expression.
    `StaticContext` | `getUnderlyingStaticContext()` | Get the underlying implementation object representing the static context of the compiled XPath expression.
    `java.util.Iterator<QName>` | `iterateExternalVariables()` | Get an iterator over the names of all the external variables.
    `XPathSelector` | `load()` | Load the compiled XPath expression to prepare it for execution.

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

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

- - ### Constructor Detail

    - #### XPathExecutable

          protected XPathExecutable​(XPathExpression exp,
                                    Processor processor,
                                    IndependentContext env)

  - ### Method Detail

    - #### load

          public XPathSelector load()

      Load the compiled XPath expression to prepare it for execution.
      Returns:
        An XPathSelector. The returned XPathSelector can be used to set up the dynamic context, and then to evaluate the expression.

    - #### asStep

          public Step<XdmItem> asStep()

      Treat the compiled XPath expression as a `Step`, so that it can be used in a call on `XdmValue.select(net.sf.saxon.s9api.streams.Step<T>)`.

      Example usage: `node.select(c.compile(".//x[a=b+2]").asStep()).asXdmValue()`

      Returns:
        a Step, whose effect is to evaluate the XPath expression (with the origin item as the initial context item)

    - #### getResultItemType

          public ItemType getResultItemType()

      Get the ItemType of the items in the result of the expression, as determined by static analysis. This is the most precise ItemType that the processor is able to determine from static examination of the expression; the actual items in the expression result are guaranteed to belong to this ItemType or to a subtype of this ItemType.
      Returns:
        the statically-determined ItemType of the result of the expression
      Since:
        9.1

    - #### getResultCardinality

          public OccurrenceIndicator getResultCardinality()

      Get the statically-determined cardinality of the result of the expression. This is the most precise cardinality that the processor is able to determine from static examination of the expression.
      Returns:
        the statically-determined cardinality of the result of the expression
      Since:
        9.1

    - #### iterateExternalVariables

          public java.util.Iterator<QName> iterateExternalVariables()

      Get an iterator over the names of all the external variables. This includes both variables that have been explicitly declared using a call to `declareVariable()`, and variables that are implicitly declared by reference in the case where the `allowUndeclaredVariables` option is set. It does not include range variables bound in a `for`, `some`, or `every` expression.

      If the `allowUndeclaredVariables` option is set, this method allows discovery of the variable references that appear in the compiled expression.

      Returns:
        an iterator over the names of the external variables defined in the XPath expression
      Since:
        9.2

    - #### getRequiredItemTypeForVariable

          public ItemType getRequiredItemTypeForVariable​(QName variableName)

      Get the required item type of a declared variable in the static context of the expression.
      Parameters:
        `variableName` - the name of a declared variable
      Returns:
        the required item type.

        If the variable was explicitly declared, this will be the item type that was set when the variable was declared. If no item type was set, it will be `ItemType.ANY_ITEM`.

        If the variable was implicitly declared by reference (which can happen only when the `allowUndeclaredVariables` option is set), the returned type will be `ItemType.ANY_ITEM`.

        If no variable with the specified QName has been declared either explicitly or implicitly, the method returns null.

      Since:
        9.2

    - #### getRequiredCardinalityForVariable

          public OccurrenceIndicator getRequiredCardinalityForVariable​(QName variableName)

      Get the required cardinality of a declared variable in the static context of the expression.
      Parameters:
        `variableName` - the name of a declared variable
      Returns:
        the required cardinality.

        If the variable was explicitly declared, this will be the occurrence indicator that was set when the variable was declared. If no item type was set, it will be `OccurrenceIndicator.ZERO_OR_MORE`.

        If the variable was implicitly declared by reference (which can happen only when the `allowUndeclaredVariables` option is set), the returned type will be `OccurrenceIndicator.ZERO_OR_MORE`.

        If no variable with the specified QName has been declared either explicitly or implicitly, the method returns null.

      Since:
        9.2

    - #### getUnderlyingExpression

          public XPathExpression getUnderlyingExpression()

      Get the underlying implementation object representing the compiled XPath expression. This method provides access to lower-level Saxon classes and methods which may be subject to change from one release to the next.
      Returns:
        the underlying compiled XPath expression.

    - #### getUnderlyingStaticContext

          public StaticContext getUnderlyingStaticContext()

      Get the underlying implementation object representing the static context of the compiled XPath expression. This method provides access to lower-level Saxon classes and methods which may be subject to change from one release to the next.
      Returns:
        the underlying static context.