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 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.