Package net.sf.saxon.xpath

## Class XPathEvaluator

- java.lang.Object
- - net.sf.saxon.xpath.XPathEvaluator

- All Implemented Interfaces:
    `javax.xml.xpath.XPath`

      public class XPathEvaluator
      extends java.lang.Object
      implements javax.xml.xpath.XPath

  XPathEvaluator implements the JAXP API for standalone XPath processing (that is, executing XPath expressions in the absence of an XSLT stylesheet). It is an implementation of the JAXP 1.3 XPath interface, with additional methods provided (a) for backwards compatibility (b) to give extra control over the XPath evaluation, and (c) to support later XPath versions (2.0, 3.0, 3.1).

  The JAXP API is designed at one level to be object-model independent, but in other respects (especially in Java SE 9) it is designed specifically with DOM in mind. The Saxon implementation makes its own decisions about how to handle non-DOM nodes. Specifically, when an expression with return type `XPathConstants.NODE` is evaluated, Saxon returns the underlying node from the native object model; when the return type is given as `XPathConstants.NODESET`, the nodes are delivered as a DOM `NodeList` if they are DOM nodes, or as a `List` otherwise.

  For an alternative XPath API, offering more complete access to Saxon capabilities, see `XPathCompiler`.

  Note that the `XPathEvaluator` links to a Saxon `Configuration` object. By default a new `Configuration` is created automatically. In many applications, however, it is desirable to share a configuration. The default configuration is not schema aware. All source documents used by XPath expressions under this evaluator must themselves be built using the `Configuration` used by this evaluator.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XPathEvaluator()` | Default constructor.
    `XPathEvaluator​(Configuration config)` | Construct an XPathEvaluator with a specified configuration.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `javax.xml.xpath.XPathExpression` | `compile​(java.lang.String expr)` | Compile an XPath 3.1 expression
    `java.lang.String` | `evaluate​(java.lang.String expr, java.lang.Object node)` | Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.
    `java.lang.Object` | `evaluate​(java.lang.String expr, java.lang.Object node, javax.xml.namespace.QName qName)` | Single-shot method to compile and execute an XPath 3.1 expression.
    `java.lang.String` | `evaluate​(java.lang.String expr, org.xml.sax.InputSource inputSource)` | Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document, returning the result as a string
    `java.lang.Object` | `evaluate​(java.lang.String expr, org.xml.sax.InputSource inputSource, javax.xml.namespace.QName qName)` | Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document
    `Configuration` | `getConfiguration()` | Get the Configuration used by this XPathEvaluator
    `javax.xml.namespace.NamespaceContext` | `getNamespaceContext()` | Get the namespace context, if one has been set using `setNamespaceContext(javax.xml.namespace.NamespaceContext)`
    `JAXPXPathStaticContext` | `getStaticContext()` | Get the current static context.
    `javax.xml.xpath.XPathFunctionResolver` | `getXPathFunctionResolver()` | Get the resolver for XPath functions
    `javax.xml.xpath.XPathVariableResolver` | `getXPathVariableResolver()` | Get the resolver for XPath variables
    `void` | `importSchema​(javax.xml.transform.Source source)` | Import a schema.
    `void` | `reset()` |
    `void` | `setNamespaceContext​(javax.xml.namespace.NamespaceContext namespaceContext)` | Set the namespace context to be used.
    `void` | `setXPathFunctionResolver​(javax.xml.xpath.XPathFunctionResolver xPathFunctionResolver)` | Set the resolver for XPath functions
    `void` | `setXPathVariableResolver​(javax.xml.xpath.XPathVariableResolver xPathVariableResolver)` | Set the resolver for XPath variables

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

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

    - ### Methods inherited from interface javax.xml.xpath.XPath

      `evaluateExpression, evaluateExpression, evaluateExpression, evaluateExpression`

- - ### Constructor Detail

    - #### XPathEvaluator

          public XPathEvaluator()

      Default constructor. Creates an XPathEvaluator with Configuration appropriate to the version of the Saxon software being run.

    - #### XPathEvaluator

          public XPathEvaluator​(Configuration config)

      Construct an XPathEvaluator with a specified configuration.
      Parameters:
        `config` - the configuration to be used. If schema-aware XPath expressions are to be used, this must be an EnterpriseConfiguration.

  - ### Method Detail

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Configuration used by this XPathEvaluator
      Returns:
        the Configuration used by this XPathEvaluator

    - #### getStaticContext

          public JAXPXPathStaticContext getStaticContext()

      Get the current static context. The caller can set properties of the returned static context to influence the way in which XPath expressions are compiled and evaluated; for example it is possible to set whether XPath 1.0 backwards compatibility is enabled or not.
      Returns:
        the static context

    - #### reset

          public void reset()

      Specified by:
        `reset` in interface `javax.xml.xpath.XPath`

    - #### setXPathVariableResolver

          public void setXPathVariableResolver​(javax.xml.xpath.XPathVariableResolver xPathVariableResolver)

      Set the resolver for XPath variables
      Specified by:
        `setXPathVariableResolver` in interface `javax.xml.xpath.XPath`
      Parameters:
        `xPathVariableResolver` - a resolver for variables

    - #### getXPathVariableResolver

          public javax.xml.xpath.XPathVariableResolver getXPathVariableResolver()

      Get the resolver for XPath variables
      Specified by:
        `getXPathVariableResolver` in interface `javax.xml.xpath.XPath`
      Returns:
        the resolver, if one has been set

    - #### setXPathFunctionResolver

          public void setXPathFunctionResolver​(javax.xml.xpath.XPathFunctionResolver xPathFunctionResolver)

      Set the resolver for XPath functions
      Specified by:
        `setXPathFunctionResolver` in interface `javax.xml.xpath.XPath`
      Parameters:
        `xPathFunctionResolver` - a resolver for XPath function calls

    - #### getXPathFunctionResolver

          public javax.xml.xpath.XPathFunctionResolver getXPathFunctionResolver()

      Get the resolver for XPath functions
      Specified by:
        `getXPathFunctionResolver` in interface `javax.xml.xpath.XPath`
      Returns:
        the resolver, if one has been set

    - #### setNamespaceContext

          public void setNamespaceContext​(javax.xml.namespace.NamespaceContext namespaceContext)

      Set the namespace context to be used.
      Specified by:
        `setNamespaceContext` in interface `javax.xml.xpath.XPath`
      Parameters:
        `namespaceContext` - The namespace context

    - #### getNamespaceContext

          public javax.xml.namespace.NamespaceContext getNamespaceContext()

      Get the namespace context, if one has been set using `setNamespaceContext(javax.xml.namespace.NamespaceContext)`
      Specified by:
        `getNamespaceContext` in interface `javax.xml.xpath.XPath`
      Returns:
        the namespace context if set, or null otherwise

    - #### importSchema

          public void importSchema​(javax.xml.transform.Source source)
                            throws SchemaException

      Import a schema. This is possible only if Saxon-EE is being used, and if the Configuration is an EnterpriseConfiguration. Having imported a schema, the types defined in that schema become part of the static context.
      Parameters:
        `source` - A Source object identifying the schema document to be loaded
      Throws:
        `SchemaException` - if the schema contained in this document is invalid
        `java.lang.UnsupportedOperationException` - if the configuration is not schema-aware

    - #### compile

          public javax.xml.xpath.XPathExpression compile​(java.lang.String expr)
                                                  throws javax.xml.xpath.XPathExpressionException

      Compile an XPath 3.1 expression
      Specified by:
        `compile` in interface `javax.xml.xpath.XPath`
      Parameters:
        `expr` - the XPath 3.1 expression to be compiled, as a string
      Returns:
        the compiled form of the expression
      Throws:
        `javax.xml.xpath.XPathExpressionException` - if there are any static errors in the expression. Note that references to undeclared variables are not treated as static errors, because variables are not pre-declared using this API.

    - #### evaluate

          public java.lang.Object evaluate​(java.lang.String expr,
                                           java.lang.Object node,
                                           javax.xml.namespace.QName qName)
                                    throws javax.xml.xpath.XPathExpressionException

      Single-shot method to compile and execute an XPath 3.1 expression.
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPath`
      Parameters:
        `expr` - The XPath 3.1 expression to be compiled and executed
        `node` - The context node for evaluation of the expression.

        This may be a NodeInfo object, representing a node in Saxon's native implementation of the data model, or it may be a node in any supported external object model: DOM, JDOM, DOM4J, or XOM, or any other model for which support has been configured in the Configuration. Note that the supporting libraries for the chosen model must be on the class path.

        Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because XPath 2.0 allows the context item to be "absent" (null). So Saxon executes the XPath expression with the context item undefined.

        `qName` - The type of result required. For details, see `XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)`
      Returns:
        the result of evaluating the expression, returned as described in `XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)`
      Throws:
        `javax.xml.xpath.XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.

    - #### evaluate

          public java.lang.String evaluate​(java.lang.String expr,
                                           java.lang.Object node)
                                    throws javax.xml.xpath.XPathExpressionException

      Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPath`
      Parameters:
        `expr` - The XPath 2.0 expression to be compiled and executed
        `node` - The context node for evaluation of the expression

        This may be a NodeInfo object, representing a node in Saxon's native implementation of the data model, or it may be a node in any supported external object model: DOM, JDOM, DOM4J, or XOM, or any other model for which support has been configured in the Configuration. Note that the supporting libraries for the chosen model must be on the class path.

        Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because XPath 2.0 allows the context item to be "absent" (null). So Saxon executes the XPath expression with the context item undefined.

      Returns:
        the result of evaluating the expression, converted to a string as if by calling the XPath string() function
      Throws:
        `javax.xml.xpath.XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.

    - #### evaluate

          public java.lang.Object evaluate​(java.lang.String expr,
                                           org.xml.sax.InputSource inputSource,
                                           javax.xml.namespace.QName qName)
                                    throws javax.xml.xpath.XPathExpressionException

      Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPath`
      Parameters:
        `expr` - The XPath 2.0 expression to be compiled and executed
        `inputSource` - The source document: this will be parsed and built into a tree, and the XPath expression will be executed with the root node of the tree as the context node.
        `qName` - The type of result required. For details, see `XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)`
      Returns:
        the result of evaluating the expression, returned as described in `XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)`
      Throws:
        `javax.xml.xpath.XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.
        `java.lang.NullPointerException` - if any of the three arguments is null

    - #### evaluate

          public java.lang.String evaluate​(java.lang.String expr,
                                           org.xml.sax.InputSource inputSource)
                                    throws javax.xml.xpath.XPathExpressionException

      Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document, returning the result as a string
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPath`
      Parameters:
        `expr` - The XPath 2.0 expression to be compiled and executed
        `inputSource` - The source document: this will be parsed and built into a tree, and the XPath expression will be executed with the root node of the tree as the context node
      Returns:
        the result of evaluating the expression, converted to a string as if by calling the XPath string() function
      Throws:
        `javax.xml.xpath.XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.
        `java.lang.NullPointerException` - if either of the two arguments is null