Module java.xml
Package javax.xml.xpath

# Interface XPath

public interface XPath
`XPath` provides access to the XPath evaluation environment and expressions. The XPath evaluation is affected by the factors described in the following table.

Evaluation of XPath Expressions
Factor | Behavior
--- | ---
context | The type of the context is implementation-dependent. If the value is null, the operation must have no dependency on the context, otherwise an XPathExpressionException will be thrown. 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.

An XPath object is not thread-safe and not reentrant. In other words, it is the application's responsibility to make sure that one `XPath` object is not used from more than one thread at any given time, and while the `evaluate` method is invoked, applications may not recursively call the `evaluate` method.

Since:
  1.5
See Also:
  - XML Path Language (XPath) Version 1.0

## Method Summary

Modifier and Type
Method
Description
`XPathExpression`
`compile(String expression)`
Compile an XPath expression for later evaluation.
`String`
`evaluate(String expression, Object item)`
Evaluate an XPath expression in the specified context and return the result as a `String`.
`Object`
`evaluate(String expression, Object item, QName returnType)`
Evaluate an `XPath` expression in the specified context and return the result as the specified type.
`String`
`evaluate(String expression, InputSource source)`
Evaluate an XPath expression in the context of the specified `InputSource` and return the result as a `String`.
`Object`
`evaluate(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.
`default XPathEvaluationResult<?>`
`evaluateExpression(String expression, Object item)`
Evaluate an XPath expression in the specified context.
`default <T> T`
`evaluateExpression(String expression, Object item, Class<T> type)`
Evaluate an XPath expression in the specified context and return the result with the type specified through the `class type`
`default XPathEvaluationResult<?>`
`evaluateExpression(String expression, InputSource source)`
Evaluate an XPath expression in the specified context.
`default <T> T`
`evaluateExpression(String expression, InputSource source, Class<T> type)`
Evaluate an XPath expression in the context of the specified `source` and return the result as specified.
`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 Details

### 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:
  `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:
  `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:
  `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(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 resovled with the `XPathFunctionResolver`.

If `expression` contains any variables, the `XPathVariableResolver` in effect at compile time will be used to resolve them.

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

### evaluate

Object evaluate(String expression, 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.

The parameter `item` represents the context the XPath expression will be operated on. The type of the context is implementation-dependent. If the value is `null`, the operation must have no dependency on the context, otherwise an XPathExpressionException will be thrown.

Implementation Note:
  The type of the context is usually `Node`.
Parameters:
  `expression` - The XPath expression.
  `item` - The context the XPath expression will be evaluated in.
  `returnType` - The result type expected to be returned by the XPath expression.
Returns:
  The result of evaluating an XPath expression as an `Object` of `returnType`.
Throws:
  `XPathExpressionException` - If `expression` cannot be evaluated.
  `IllegalArgumentException` - If `returnType` is not one of the types defined in `XPathConstants` ( `NUMBER`, `STRING`, `BOOLEAN`, `NODE` or `NODESET`).
  `NullPointerException` - If `expression or returnType` is `null`.

### evaluate

String evaluate(String expression, 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.

The parameter `item` represents the context the XPath expression will be operated on. The type of the context is implementation-dependent. If the value is `null`, the operation must have no dependency on the context, otherwise an XPathExpressionException will be thrown.

Implementation Note:
  The type of the context is usually `Node`.
Parameters:
  `expression` - The XPath expression.
  `item` - The context the XPath expression will be evaluated in.
Returns:
  The result of evaluating an XPath expression as a `String`.
Throws:
  `XPathExpressionException` - If `expression` cannot be evaluated.
  `NullPointerException` - If `expression` is `null`.

### evaluate

Object evaluate(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.

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.
  `IllegalArgumentException` - If `returnType` is not one of the types defined in `XPathConstants`.
  `NullPointerException` - If `expression, source or returnType` is `null`.

### evaluate

String evaluate(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.

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.
  `NullPointerException` - If `expression or source` is `null`.

### evaluateExpression

default <T> T evaluateExpression(String expression, Object item, Class<T> type) throws XPathExpressionException
Evaluate an XPath expression in the specified context and return the result with the type specified through the `class type`

The parameter `item` represents the context the XPath expression will be operated on. The type of the context is implementation-dependent. If the value is `null`, the operation must have no dependency on the context, otherwise an XPathExpressionException will be thrown.

Implementation Requirements:
  The default implementation in the XPath API is equivalent to:

           (T)evaluate(expression, item,
                 XPathEvaluationResult.XPathResultType.getQNameType(type));

  Since the `evaluate` method does not support the `ANY` type, specifying XPathEvaluationResult as the type will result in IllegalArgumentException. Any implementation supporting the `ANY` type must override this method.
Implementation Note:
  The type of the context is usually `Node`.
Type Parameters:
  `T` - The class type that will be returned by the XPath expression.
Parameters:
  `expression` - The XPath expression.
  `item` - The context the XPath expression will be evaluated in.
  `type` - The class type expected to be returned by the XPath expression, must be one of the types described in section 3.2 Class types in the package summary.
Returns:
  The result of evaluating the expression.
Throws:
  `XPathExpressionException` - If the expression cannot be evaluated.
  `IllegalArgumentException` - If `type` is not of the types corresponding to the types defined in the `XPathEvaluationResult.XPathResultType`, or XPathEvaluationResult is specified as the type but an implementation supporting the `ANY` type is not available.
  `NullPointerException` - If `expression or type` is `null`.
Since:
  9

### evaluateExpression

default XPathEvaluationResult<?> evaluateExpression(String expression, Object item) throws XPathExpressionException
Evaluate an XPath expression in the specified context. This is equivalent to calling `evaluateExpression(String expression, Object item, Class type)` with type `XPathEvaluationResult`:

         evaluateExpression(expression, item, XPathEvaluationResult.class);

The parameter `item` represents the context the XPath expression will be operated on. The type of the context is implementation-dependent. If the value is `null`, the operation must have no dependency on the context, otherwise an XPathExpressionException will be thrown.

Implementation Requirements:
  The default implementation in the XPath API is equivalent to:

           evaluateExpression(expression, item, XPathEvaluationResult.class);

  Since the `evaluate` method does not support the `ANY` type, the default implementation of this method will always throw an IllegalArgumentException. Any implementation supporting the `ANY` type must therefore override this method.
Implementation Note:
  The type of the context is usually `Node`.
Parameters:
  `expression` - The XPath expression.
  `item` - The context the XPath expression will be evaluated in.
Returns:
  The result of evaluating the expression.
Throws:
  `XPathExpressionException` - If the expression cannot be evaluated.
  `IllegalArgumentException` - If the implementation of this method does not support the `ANY` type.
  `NullPointerException` - If `expression` is `null`.
Since:
  9

### evaluateExpression

default <T> T evaluateExpression(String expression, InputSource source, Class<T> type) throws XPathExpressionException
Evaluate an XPath expression in the context of the specified `source` and return the result as specified.

This method builds a data model for the `InputSource` and calls `evaluateExpression(String expression, Object item, Class type)` on the resulting document object. The data model is usually `Document`

Implementation Requirements:
  The default implementation in the XPath API is equivalent to:

                 (T)evaluate(expression, source,
                      XPathEvaluationResult.XPathResultType.getQNameType(type));

  Since the `evaluate` method does not support the `ANY` type, specifying XPathEvaluationResult as the type will result in IllegalArgumentException. Any implementation supporting the `ANY` type must override this method.
Type Parameters:
  `T` - The class type that will be returned by the XPath expression.
Parameters:
  `expression` - The XPath expression.
  `source` - The input source of the document to evaluate over.
  `type` - The class type expected to be returned by the XPath expression, must be one of the types described in section 3.2 Class types in the package summary.
Returns:
  The result of evaluating the expression.
Throws:
  `XPathExpressionException` - If the expression cannot be evaluated.
  `IllegalArgumentException` - If `type` is not of the types corresponding to the types defined in the `XPathResultType`, or XPathEvaluationResult is specified as the type but an implementation supporting the `ANY` type is not available.
  `NullPointerException` - If `expression, source or type`is `null`.
Since:
  9

### evaluateExpression

default XPathEvaluationResult<?> evaluateExpression(String expression, InputSource source) throws XPathExpressionException
Evaluate an XPath expression in the specified context. This is equivalent to calling `evaluateExpression(String expression, Object item, Class type)` with type `XPathEvaluationResult`:

         evaluateExpression(expression, item, XPathEvaluationResult.class);

Implementation Requirements:
  The default implementation in the XPath API is equivalent to:

           evaluateExpression(expression, source, XPathEvaluationResult.class);

  Since the `evaluate` method does not support the `ANY` type, the default implementation of this method will always throw an IllegalArgumentException. Any implementation supporting the `ANY` type must therefore override this method.
Parameters:
  `expression` - The XPath expression.
  `source` - The input source of the document to evaluate over.
Returns:
  The result of evaluating the expression.
Throws:
  `XPathExpressionException` - If the expression cannot be evaluated.
  `IllegalArgumentException` - If the implementation of this method does not support the `ANY` type.
  `NullPointerException` - If `expression or source` is `null`.
Since:
  9