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