Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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
`XPathExpression` | `compile(String expression)` Compile an XPath expression for later evaluation.
`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.
`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.
`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:
    `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.

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

  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.

  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 (a node, 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.
    `IllegalArgumentException` - If `returnType` is not one of the types defined in `XPathConstants`.
    `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.

  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 (a node, 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.
    `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.

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

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 1993, 2010, Oracle and/or its affiliates. All rights reserved.