javax.xml.xpath

## Interface XPath

-     public interface XPath

  `XPath` provides access to the XPath evaluation environment and expressions.

  Evaluation of XPath Expressions.
  context | If a request is made to evaluate the expression in the absence of a context item, an empty document node will be used for the context. For the purposes of evaluating XPath expressions, a DocumentFragment is treated like a Document node.
  variables | If the expression contains a variable reference, its value will be found through the `XPathVariableResolver` set with `setXPathVariableResolver(XPathVariableResolver resolver)`. An `XPathExpressionException` is raised if the variable resolver is undefined or the resolver returns `null` for the variable. The value of a variable must be immutable through the course of any single evaluation.
  functions | If the expression contains a function reference, the function will be found through the `XPathFunctionResolver` set with `setXPathFunctionResolver(XPathFunctionResolver resolver)`. An `XPathExpressionException` is raised if the function resolver is undefined or the function resolver returns `null` for the function.
  QNames | QNames in the expression are resolved against the XPath namespace context set with `setNamespaceContext(NamespaceContext nsContext)`.
  result | This result of evaluating an expression is converted to an instance of the desired return type. Valid return types are defined in `XPathConstants`. Conversion to the return type follows XPath conversion rules.

  Since:
    1.5
  Version:
    $Revision: 569998 $, $Date: 2007-08-27 00:40:02 -0400 (Mon, 27 Aug 2007) $
  Author:
    Norman Walsh, Jeff Suttor
  See Also:
    XML Path Language (XPath) Version 1.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `XPathExpression` | `compile(java.lang.String expression)` Compile an XPath expression for later evaluation.
    `java.lang.String` | `evaluate(java.lang.String expression, InputSource source)` Evaluate an XPath expression in the context of the specified `InputSource` and return the result as a `String`.
    `java.lang.Object` | `evaluate(java.lang.String expression, InputSource source, QName returnType)` Evaluate an XPath expression in the context of the specified `InputSource` and return the result as the specified type.
    `java.lang.String` | `evaluate(java.lang.String expression, java.lang.Object item)` Evaluate an XPath expression in the specified context and return the result as a `String`.
    `java.lang.Object` | `evaluate(java.lang.String expression, java.lang.Object item, QName returnType)` Evaluate an `XPath` expression in the specified context and return the result as the specified type.
    `NamespaceContext` | `getNamespaceContext()` Return the current namespace context.
    `XPathFunctionResolver` | `getXPathFunctionResolver()` Return the current function resolver.
    `XPathVariableResolver` | `getXPathVariableResolver()` Return the current variable resolver.
    `void` | `reset()` Reset this `XPath` to its original configuration.
    `void` | `setNamespaceContext(NamespaceContext nsContext)` Establish a namespace context.
    `void` | `setXPathFunctionResolver(XPathFunctionResolver resolver)` Establish a function resolver.
    `void` | `setXPathVariableResolver(XPathVariableResolver resolver)` Establish a variable resolver.

- - ### Method Detail

    - #### reset

          void reset()

      Reset this `XPath` to its original configuration.

      `XPath` is reset to the same state as when it was created with `XPathFactory.newXPath()`. `reset()` is designed to allow the reuse of existing `XPath`s thus saving resources associated with the creation of new `XPath`s.

      The reset `XPath` is not guaranteed to have the same `XPathFunctionResolver`, `XPathVariableResolver` or `NamespaceContext` `Object`s, e.g. `Object.equals(Object obj)`. It is guaranteed to have a functionally equal `XPathFunctionResolver`, `XPathVariableResolver` and `NamespaceContext`.

    - #### setXPathVariableResolver

          void setXPathVariableResolver(XPathVariableResolver resolver)

      Establish a variable resolver.

      A `NullPointerException` is thrown if `resolver` is `null`.

      Parameters:
        `resolver` - Variable resolver.
      Throws:
        `java.lang.NullPointerException` - If `resolver` is `null`.

    - #### getXPathVariableResolver

          XPathVariableResolver getXPathVariableResolver()

      Return the current variable resolver.

      `null` is returned in no variable resolver is in effect.

      Returns:
        Current variable resolver.

    - #### setXPathFunctionResolver

          void setXPathFunctionResolver(XPathFunctionResolver resolver)

      Establish a function resolver.

      A `NullPointerException` is thrown if `resolver` is `null`.

      Parameters:
        `resolver` - XPath function resolver.
      Throws:
        `java.lang.NullPointerException` - If `resolver` is `null`.

    - #### getXPathFunctionResolver

          XPathFunctionResolver getXPathFunctionResolver()

      Return the current function resolver.

      `null` is returned in no function resolver is in effect.

      Returns:
        Current function resolver.

    - #### setNamespaceContext

          void setNamespaceContext(NamespaceContext nsContext)

      Establish a namespace context.

      A `NullPointerException` is thrown if `nsContext` is `null`.

      Parameters:
        `nsContext` - Namespace context to use.
      Throws:
        `java.lang.NullPointerException` - If `nsContext` is `null`.

    - #### getNamespaceContext

          NamespaceContext getNamespaceContext()

      Return the current namespace context.

      `null` is returned in no namespace context is in effect.

      Returns:
        Current Namespace context.

    - #### compile

          XPathExpression compile(java.lang.String expression)
                           throws XPathExpressionException

      Compile an XPath expression for later evaluation.

      If `expression` contains any `XPathFunction`s, they must be available via the `XPathFunctionResolver`. An `XPathExpressionException` will be thrown if the `XPathFunction` cannot be resolved with the `XPathFunctionResolver`.

      If `expression` is `null`, a `NullPointerException` is thrown.

      Parameters:
        `expression` - The XPath expression.
      Returns:
        Compiled XPath expression.
      Throws:
        `XPathExpressionException` - If `expression` cannot be compiled.
        `java.lang.NullPointerException` - If `expression` is `null`.

    - #### evaluate

          java.lang.Object evaluate(java.lang.String expression,
                                    java.lang.Object item,
                                    QName returnType)
                             throws XPathExpressionException

      Evaluate an `XPath` expression in the specified context and return the result as the specified type.

      See Evaluation of XPath Expressions for context item evaluation, variable, function and `QName` resolution and return type conversion.

      If `returnType` is not one of the types defined in `XPathConstants` ( `NUMBER`, `STRING`, `BOOLEAN`, `NODE` or `NODESET`) then an `IllegalArgumentException` is thrown.

      If a `null` value is provided for `item`, an empty document will be used for the context. If `expression` or `returnType` is `null`, then a `NullPointerException` is thrown.

      Parameters:
        `expression` - The XPath expression.
        `item` - The starting context (node or node list, for example).
        `returnType` - The desired return type.
      Returns:
        Result of evaluating an XPath expression as an `Object` of `returnType`.
      Throws:
        `XPathExpressionException` - If `expression` cannot be evaluated.
        `java.lang.IllegalArgumentException` - If `returnType` is not one of the types defined in `XPathConstants`.
        `java.lang.NullPointerException` - If `expression` or `returnType` is `null`.

    - #### evaluate

          java.lang.String evaluate(java.lang.String expression,
                                    java.lang.Object item)
                             throws XPathExpressionException

      Evaluate an XPath expression in the specified context and return the result as a `String`.

      This method calls `evaluate(String expression, Object item, QName returnType)` with a `returnType` of `XPathConstants.STRING`.

      See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

      If a `null` value is provided for `item`, an empty document will be used for the context. If `expression` is `null`, then a `NullPointerException` is thrown.

      Parameters:
        `expression` - The XPath expression.
        `item` - The starting context (node or node list, for example).
      Returns:
        The `String` that is the result of evaluating the expression and converting the result to a `String`.
      Throws:
        `XPathExpressionException` - If `expression` cannot be evaluated.
        `java.lang.NullPointerException` - If `expression` is `null`.

    - #### evaluate

          java.lang.Object evaluate(java.lang.String expression,
                                    InputSource source,
                                    QName returnType)
                             throws XPathExpressionException

      Evaluate an XPath expression in the context of the specified `InputSource` and return the result as the specified type.

      This method builds a data model for the `InputSource` and calls `evaluate(String expression, Object item, QName returnType)` on the resulting document object.

      See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

      If `returnType` is not one of the types defined in `XPathConstants`, then an `IllegalArgumentException` is thrown.

      If `expression`, `source` or `returnType` is `null`, then a `NullPointerException` is thrown.

      Parameters:
        `expression` - The XPath expression.
        `source` - The input source of the document to evaluate over.
        `returnType` - The desired return type.
      Returns:
        The `Object` that encapsulates the result of evaluating the expression.
      Throws:
        `XPathExpressionException` - If expression cannot be evaluated.
        `java.lang.IllegalArgumentException` - If `returnType` is not one of the types defined in `XPathConstants`.
        `java.lang.NullPointerException` - If `expression`, `source` or `returnType` is `null`.

    - #### evaluate

          java.lang.String evaluate(java.lang.String expression,
                                    InputSource source)
                             throws XPathExpressionException

      Evaluate an XPath expression in the context of the specified `InputSource` and return the result as a `String`.

      This method calls `evaluate(String expression, InputSource source, QName returnType)` with a `returnType` of `XPathConstants.STRING`.

      See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

      If `expression` or `source` is `null`, then a `NullPointerException` is thrown.

      Parameters:
        `expression` - The XPath expression.
        `source` - The `InputSource` of the document to evaluate over.
      Returns:
        The `String` that is the result of evaluating the expression and converting the result to a `String`.
      Throws:
        `XPathExpressionException` - If expression cannot be evaluated.
        `java.lang.NullPointerException` - If `expression` or `source` is `null`.

Copyright © 1999-2010 The Apache Software Foundation. All Rights Reserved.