## 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: 446598 $, $Date: 2006-09-15 08:55:40 -0400 (Fri, 15 Sep 2006) $
Author:
  Norman Walsh, Jeff Suttor
See Also:
  XML Path Language (XPath) Version 1.0

Method Summary
`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

    public 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

    public 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

    public XPathVariableResolver getXPathVariableResolver()

  Return the current variable resolver.

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

  Returns:
    Current variable resolver.

### setXPathFunctionResolver

    public 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

    public XPathFunctionResolver getXPathFunctionResolver()

  Return the current function resolver.

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

  Returns:
    Current function resolver.

### setNamespaceContext

    public 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

    public NamespaceContext getNamespaceContext()

  Return the current namespace context.

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

  Returns:
    Current Namespace context.

### compile

    public 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 resovled 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

    public 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

    public 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

    public 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

    public 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-2007 The Apache Software Foundation. All Rights Reserved.