# XPath

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

# XPath


`
public


interface
XPath
`


`


`

|-----------------------|
| javax.xml.xpath.XPath |

<br />

*** ** * ** ***

<br />

`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](https://developer.android.com/reference/javax/xml/xpath/XPathVariableResolver) set with [setXPathVariableResolver(javax.xml.xpath.XPathVariableResolver)](https://developer.android.com/reference/javax/xml/xpath/XPath#setXPathVariableResolver(javax.xml.xpath.XPathVariableResolver)). An [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/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. <br /> |
| functions | If the expression contains a function reference, the function will be found through the [XPathFunctionResolver](https://developer.android.com/reference/javax/xml/xpath/XPathFunctionResolver) set with [setXPathFunctionResolver(javax.xml.xpath.XPathFunctionResolver)](https://developer.android.com/reference/javax/xml/xpath/XPath#setXPathFunctionResolver(javax.xml.xpath.XPathFunctionResolver)). An [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/XPathExpressionException) is raised if the function resolver is undefined or the function resolver returns `null` for the function. <br />                                                                            |
| QNames    | QNames in the expression are resolved against the XPath namespace context set with [setNamespaceContext(javax.xml.namespace.NamespaceContext)](https://developer.android.com/reference/javax/xml/xpath/XPath#setNamespaceContext(javax.xml.namespace.NamespaceContext)).                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| result    | This result of evaluating an expression is converted to an instance of the desired return type. Valid return types are defined in [XPathConstants](https://developer.android.com/reference/javax/xml/xpath/XPathConstants). Conversion to the return type follows XPath conversion rules. <br />                                                                                                                                                                                                                                                                                                                                                                                                                      |

<br />

**See also:**

- [XML Path Language (XPath) Version 1.0](http://www.w3.org/TR/xpath)

## Summary

|                                                                                                                                                                                                                                                                                                                                    ### Public methods                                                                                                                                                                                                                                                                                                                                    ||
|--------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` abstract `[XPathExpression](https://developer.android.com/reference/javax/xml/xpath/XPathExpression)             | ` `[compile](https://developer.android.com/reference/javax/xml/xpath/XPath#compile(java.lang.String))`(`[String](https://developer.android.com/reference/java/lang/String)` expression) ` <br /> Compile an XPath expression for later evaluation.                                                                                                                                                                                                                                                                                                                   |
| ` abstract `[Object](https://developer.android.com/reference/java/lang/Object)                                     | ` `[evaluate](https://developer.android.com/reference/javax/xml/xpath/XPath#evaluate(java.lang.String,%20java.lang.Object,%20javax.xml.namespace.QName))`(`[String](https://developer.android.com/reference/java/lang/String)` expression, `[Object](https://developer.android.com/reference/java/lang/Object)` item, `[QName](https://developer.android.com/reference/javax/xml/namespace/QName)` returnType) ` <br /> Evaluate an `XPath` expression in the specified context and return the result as the specified type.                                         |
| ` abstract `[String](https://developer.android.com/reference/java/lang/String)                                     | ` `[evaluate](https://developer.android.com/reference/javax/xml/xpath/XPath#evaluate(java.lang.String,%20java.lang.Object))`(`[String](https://developer.android.com/reference/java/lang/String)` expression, `[Object](https://developer.android.com/reference/java/lang/Object)` item) ` <br /> Evaluate an XPath expression in the specified context and return the result as a `String`.                                                                                                                                                                         |
| ` abstract `[Object](https://developer.android.com/reference/java/lang/Object)                                     | ` `[evaluate](https://developer.android.com/reference/javax/xml/xpath/XPath#evaluate(java.lang.String,%20org.xml.sax.InputSource,%20javax.xml.namespace.QName))`(`[String](https://developer.android.com/reference/java/lang/String)` expression, `[InputSource](https://developer.android.com/reference/org/xml/sax/InputSource)` source, `[QName](https://developer.android.com/reference/javax/xml/namespace/QName)` returnType) ` <br /> Evaluate an XPath expression in the context of the specified `InputSource` and return the result as the specified type. |
| ` abstract `[String](https://developer.android.com/reference/java/lang/String)                                     | ` `[evaluate](https://developer.android.com/reference/javax/xml/xpath/XPath#evaluate(java.lang.String,%20org.xml.sax.InputSource))`(`[String](https://developer.android.com/reference/java/lang/String)` expression, `[InputSource](https://developer.android.com/reference/org/xml/sax/InputSource)` source) ` <br /> Evaluate an XPath expression in the context of the specified `InputSource` and return the result as a `String`.                                                                                                                               |
| ` abstract `[NamespaceContext](https://developer.android.com/reference/javax/xml/namespace/NamespaceContext)       | ` `[getNamespaceContext](https://developer.android.com/reference/javax/xml/xpath/XPath#getNamespaceContext())`() ` <br /> Return the current namespace context.                                                                                                                                                                                                                                                                                                                                                                                                      |
| ` abstract `[XPathFunctionResolver](https://developer.android.com/reference/javax/xml/xpath/XPathFunctionResolver) | ` `[getXPathFunctionResolver](https://developer.android.com/reference/javax/xml/xpath/XPath#getXPathFunctionResolver())`() ` <br /> Return the current function resolver.                                                                                                                                                                                                                                                                                                                                                                                            |
| ` abstract `[XPathVariableResolver](https://developer.android.com/reference/javax/xml/xpath/XPathVariableResolver) | ` `[getXPathVariableResolver](https://developer.android.com/reference/javax/xml/xpath/XPath#getXPathVariableResolver())`() ` <br /> Return the current variable resolver.                                                                                                                                                                                                                                                                                                                                                                                            |
| ` abstract void`                                                                                                   | ` `[reset](https://developer.android.com/reference/javax/xml/xpath/XPath#reset())`() ` <br /> Reset this `XPath` to its original configuration.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ` abstract void`                                                                                                   | ` `[setNamespaceContext](https://developer.android.com/reference/javax/xml/xpath/XPath#setNamespaceContext(javax.xml.namespace.NamespaceContext))`(`[NamespaceContext](https://developer.android.com/reference/javax/xml/namespace/NamespaceContext)` nsContext) ` <br /> Establish a namespace context.                                                                                                                                                                                                                                                             |
| ` abstract void`                                                                                                   | ` `[setXPathFunctionResolver](https://developer.android.com/reference/javax/xml/xpath/XPath#setXPathFunctionResolver(javax.xml.xpath.XPathFunctionResolver))`(`[XPathFunctionResolver](https://developer.android.com/reference/javax/xml/xpath/XPathFunctionResolver)` resolver) ` <br /> Establish a function resolver.                                                                                                                                                                                                                                             |
| ` abstract void`                                                                                                   | ` `[setXPathVariableResolver](https://developer.android.com/reference/javax/xml/xpath/XPath#setXPathVariableResolver(javax.xml.xpath.XPathVariableResolver))`(`[XPathVariableResolver](https://developer.android.com/reference/javax/xml/xpath/XPathVariableResolver)` resolver) ` <br /> Establish a variable resolver.                                                                                                                                                                                                                                             |

## Public methods

### compile

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract XPathExpression compile (String expression)
```

<br />

Compile an XPath expression for later evaluation.

If `expression` contains any [XPathFunction](https://developer.android.com/reference/javax/xml/xpath/XPathFunction)s,
they must be available via the [XPathFunctionResolver](https://developer.android.com/reference/javax/xml/xpath/XPathFunctionResolver).
An [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/XPathExpressionException) will be thrown if the `XPathFunction`
cannot be resolved with the `XPathFunctionResolver`.

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

<br />

<br />

|                      Parameters                      ||
|--------------|----------------------------------------|
| `expression` | `String`: The XPath expression. <br /> |

|                                                            Returns                                                            ||
|--------------------------------------------------------------------------------------------|-----------------------------------|
| [XPathExpression](https://developer.android.com/reference/javax/xml/xpath/XPathExpression) | Compiled XPath expression. <br /> |

|                                                                      Throws                                                                       ||
|--------------------------------------------------------------------------------------------------------------|-------------------------------------|
| [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/XPathExpressionException) | If `expression` cannot be compiled. |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)               | If `expression` is `null`.          |

### evaluate

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract Object evaluate (String expression, 
                Object item, 
                QName returnType)
```

<br />

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

See [Evaluation of XPath Expressions](https://developer.android.com/reference/javax/xml/xpath/XPath#XPath-evaluation) for context item evaluation,
variable, function and `QName` resolution and return type conversion.

If `returnType` is not one of the types defined in [XPathConstants](https://developer.android.com/reference/javax/xml/xpath/XPathConstants) (
[NUMBER](https://developer.android.com/reference/javax/xml/xpath/XPathConstants#NUMBER),
[STRING](https://developer.android.com/reference/javax/xml/xpath/XPathConstants#STRING),
[BOOLEAN](https://developer.android.com/reference/javax/xml/xpath/XPathConstants#BOOLEAN),
[NODE](https://developer.android.com/reference/javax/xml/xpath/XPathConstants#NODE) or
[NODESET](https://developer.android.com/reference/javax/xml/xpath/XPathConstants#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.

<br />

<br />

|                                      Parameters                                       ||
|--------------|-------------------------------------------------------------------------|
| `expression` | `String`: The XPath expression. <br />                                  |
| `item`       | `Object`: The starting context (node or node list, for example). <br /> |
| `returnType` | `QName`: The desired return type. <br />                                |

|                                                                       Returns                                                                       ||
|--------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [Object](https://developer.android.com/reference/java/lang/Object) | Result of evaluating an XPath expression as an `Object` of `returnType`. <br /> |

|                                                                                                                           Throws                                                                                                                           ||
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/XPathExpressionException) | If `expression` cannot be evaluated.                                                                                                         |
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)       | If `returnType` is not one of the types defined in [XPathConstants](https://developer.android.com/reference/javax/xml/xpath/XPathConstants). |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)               | If `expression` or `returnType` is `null`.                                                                                                   |

### evaluate

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract String evaluate (String expression, 
                Object item)
```

<br />

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

This method calls [evaluate(java.lang.String, java.lang.Object, javax.xml.namespace.QName)](https://developer.android.com/reference/javax/xml/xpath/XPath#evaluate(java.lang.String,%20java.lang.Object,%20javax.xml.namespace.QName)) with a `returnType` of
[XPathConstants.STRING](https://developer.android.com/reference/javax/xml/xpath/XPathConstants#STRING).

See [Evaluation of XPath Expressions](https://developer.android.com/reference/javax/xml/xpath/XPath#XPath-evaluation) 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.

<br />

<br />

|                                      Parameters                                       ||
|--------------|-------------------------------------------------------------------------|
| `expression` | `String`: The XPath expression. <br />                                  |
| `item`       | `Object`: The starting context (node or node list, for example). <br /> |

|                                                                                     Returns                                                                                      ||
|--------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| [String](https://developer.android.com/reference/java/lang/String) | The `String` that is the result of evaluating the expression and converting the result to a `String`. <br /> |

|                                                                       Throws                                                                       ||
|--------------------------------------------------------------------------------------------------------------|--------------------------------------|
| [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/XPathExpressionException) | If `expression` cannot be evaluated. |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)               | If `expression` is `null`.           |

### evaluate

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract Object evaluate (String expression, 
                InputSource source, 
                QName returnType)
```

<br />

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](https://developer.android.com/reference/org/xml/sax/InputSource) and calls
[evaluate(java.lang.String, java.lang.Object, javax.xml.namespace.QName)](https://developer.android.com/reference/javax/xml/xpath/XPath#evaluate(java.lang.String,%20java.lang.Object,%20javax.xml.namespace.QName)) on the resulting document object.

See [Evaluation of XPath Expressions](https://developer.android.com/reference/javax/xml/xpath/XPath#XPath-evaluation) for context item evaluation,
variable, function and QName resolution and return type conversion.

If `returnType` is not one of the types defined in [XPathConstants](https://developer.android.com/reference/javax/xml/xpath/XPathConstants),
then an `IllegalArgumentException` is thrown.

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

<br />

<br />

|                                       Parameters                                       ||
|--------------|--------------------------------------------------------------------------|
| `expression` | `String`: The XPath expression. <br />                                   |
| `source`     | `InputSource`: The input source of the document to evaluate over. <br /> |
| `returnType` | `QName`: The desired return type. <br />                                 |

|                                                                      Returns                                                                       ||
|--------------------------------------------------------------------|--------------------------------------------------------------------------------|
| [Object](https://developer.android.com/reference/java/lang/Object) | The `Object` that encapsulates the result of evaluating the expression. <br /> |

|                                                                                                                           Throws                                                                                                                           ||
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/XPathExpressionException) | If expression cannot be evaluated.                                                                                                           |
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)       | If `returnType` is not one of the types defined in [XPathConstants](https://developer.android.com/reference/javax/xml/xpath/XPathConstants). |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)               | If `expression`, `source` or `returnType` is `null`.                                                                                         |

### evaluate

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract String evaluate (String expression, 
                InputSource source)
```

<br />

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

This method calls [evaluate(java.lang.String, org.xml.sax.InputSource, javax.xml.namespace.QName)](https://developer.android.com/reference/javax/xml/xpath/XPath#evaluate(java.lang.String,%20org.xml.sax.InputSource,%20javax.xml.namespace.QName)) with a
`returnType` of [XPathConstants.STRING](https://developer.android.com/reference/javax/xml/xpath/XPathConstants#STRING).

See [Evaluation of XPath Expressions](https://developer.android.com/reference/javax/xml/xpath/XPath#XPath-evaluation) for context item evaluation,
variable, function and QName resolution and return type conversion.

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

<br />

<br />

|                                       Parameters                                        ||
|--------------|---------------------------------------------------------------------------|
| `expression` | `String`: The XPath expression. <br />                                    |
| `source`     | `InputSource`: The `InputSource` of the document to evaluate over. <br /> |

|                                                                                     Returns                                                                                      ||
|--------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| [String](https://developer.android.com/reference/java/lang/String) | The `String` that is the result of evaluating the expression and converting the result to a `String`. <br /> |

|                                                                        Throws                                                                        ||
|--------------------------------------------------------------------------------------------------------------|----------------------------------------|
| [XPathExpressionException](https://developer.android.com/reference/javax/xml/xpath/XPathExpressionException) | If expression cannot be evaluated.     |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)               | If `expression` or `source` is `null`. |

### getNamespaceContext

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract NamespaceContext getNamespaceContext ()
```

<br />

Return the current namespace context.

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

<br />

<br />

|                                                               Returns                                                               ||
|--------------------------------------------------------------------------------------------------|-----------------------------------|
| [NamespaceContext](https://developer.android.com/reference/javax/xml/namespace/NamespaceContext) | Current Namespace context. <br /> |

### getXPathFunctionResolver

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract XPathFunctionResolver getXPathFunctionResolver ()
```

<br />

Return the current function resolver.

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

<br />

<br />

|                                                                  Returns                                                                  ||
|--------------------------------------------------------------------------------------------------------|-----------------------------------|
| [XPathFunctionResolver](https://developer.android.com/reference/javax/xml/xpath/XPathFunctionResolver) | Current function resolver. <br /> |

### getXPathVariableResolver

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract XPathVariableResolver getXPathVariableResolver ()
```

<br />

Return the current variable resolver.

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

<br />

<br />

|                                                                  Returns                                                                  ||
|--------------------------------------------------------------------------------------------------------|-----------------------------------|
| [XPathVariableResolver](https://developer.android.com/reference/javax/xml/xpath/XPathVariableResolver) | Current variable resolver. <br /> |

### reset

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract void reset ()
```

<br />

Reset this `XPath` to its original configuration.

`XPath` is reset to the same state as when it was created with
[XPathFactory.newXPath()](https://developer.android.com/reference/javax/xml/xpath/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](https://developer.android.com/reference/javax/xml/xpath/XPathFunctionResolver), [XPathVariableResolver](https://developer.android.com/reference/javax/xml/xpath/XPathVariableResolver)
or [NamespaceContext](https://developer.android.com/reference/javax/xml/namespace/NamespaceContext) `Object`s, e.g. [Object.equals(Object obj)](https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)).
It is guaranteed to have a functionally equal `XPathFunctionResolver`, `XPathVariableResolver`
and `NamespaceContext`.

<br />

<br />

### setNamespaceContext

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract void setNamespaceContext (NamespaceContext nsContext)
```

<br />

Establish a namespace context.

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

<br />

<br />

|                            Parameters                             ||
|-------------|------------------------------------------------------|
| `nsContext` | `NamespaceContext`: Namespace context to use. <br /> |

|                                                          Throws                                                           ||
|------------------------------------------------------------------------------------------------|---------------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException) | If `nsContext` is `null`. |

### setXPathFunctionResolver

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract void setXPathFunctionResolver (XPathFunctionResolver resolver)
```

<br />

Establish a function resolver.

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

<br />

<br />

|                              Parameters                              ||
|------------|----------------------------------------------------------|
| `resolver` | `XPathFunctionResolver`: XPath function resolver. <br /> |

|                                                          Throws                                                          ||
|------------------------------------------------------------------------------------------------|--------------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException) | If `resolver` is `null`. |

### setXPathVariableResolver

Added in [API level 8](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public abstract void setXPathVariableResolver (XPathVariableResolver resolver)
```

<br />

Establish a variable resolver.

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

<br />

<br />

|                           Parameters                           ||
|------------|----------------------------------------------------|
| `resolver` | `XPathVariableResolver`: Variable resolver. <br /> |

|                                                          Throws                                                          ||
|------------------------------------------------------------------------------------------------|--------------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException) | If `resolver` is `null`. |