Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.jaxen
Interface XPath

All Known Implementing Classes:
  BaseXPath

public interface XPath

Defines the interface to an object which represents an XPath 1.0 expression which can be evaluated against a variety of different XML object models.

Most of the evaluation methods take a context object. This is typically a node or node-set object (which is typically a `List` of node objects) or a Jaxen `Context` object. A null context is allowed, meaning that there are no XML nodes on which to evaluate.

Author:
  bob mcwhirter, James Strachan
See Also:
  `XPath for dom4j`, `XPath for JDOM`, `XPath for W3C DOM`

Method Summary
`void` | `addNamespace(String prefix, String uri)` Add a namespace prefix-to-URI mapping for this XPath expression.
`boolean` | `booleanValueOf(Object context)` Retrieve the boolean value of the first node in document order returned by this XPath expression when evaluated in the given context.
`Object` | `evaluate(Object context)` Evaluate this XPath against the given context.
`FunctionContext` | `getFunctionContext()` Retrieve the `FunctionContext` used by this XPath expression.
`NamespaceContext` | `getNamespaceContext()` Retrieve the `NamespaceContext` used by this XPath expression.
`Navigator` | `getNavigator()` Retrieve the XML object-model-specific `Navigator` used to evaluate this XPath expression.
`VariableContext` | `getVariableContext()` Retrieve the `VariableContext` used by this XPath expression.
`Number` | `numberValueOf(Object context)` Retrieve the number-value of the first node in document order returned by this XPath expression when evaluated in the given context.
`List` | `selectNodes(Object context)` Select all nodes that are selectable by this XPath expression.
`Object` | `selectSingleNode(Object context)` Return the first node in document order that is selected by this XPath expression.
`void` | `setFunctionContext(FunctionContext functionContext)` Set a `FunctionContext` for this XPath expression.
`void` | `setNamespaceContext(NamespaceContext namespaceContext)` Set a `NamespaceContext` for this XPath expression.
`void` | `setVariableContext(VariableContext variableContext)` Set a `VariableContext` for this XPath expression.
`String` | `stringValueOf(Object context)` Retrieve a string-value interpretation of this XPath expression when evaluated against the given context.
`String` | `valueOf(Object context)` Deprecated. use `stringValueOf(Object)` instead

Method Detail

### evaluate

    public Object evaluate(Object context)
                    throws JaxenException

  Evaluate this XPath against the given context.

  The context of evaluation my be a document, an element, or a set of elements.

  If the expression evaluates to an XPath string, number, or boolean type, then the equivalent Java object type is returned. Otherwise, if the result is a node-set, then the returned value is a `List`.

  When using this method, one must be careful to test the class of the returned objects, and of each of the composite members if a `List` is returned. If the returned members are XML nodes, they will be the actual `Document`, `Element` or `Attribute` objects as defined by the concrete XML object-model implementation, directly from the context document. This method does not return copies of anything. It merely returns references to nodes within the source document.

  Parameters:
    `context` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the result of evaluating the XPath expression against the supplied context
  Throws:
    `JaxenException` - if an error occurs while attempting to evaluate the expression

### valueOf

    public String valueOf(Object context)
                   throws JaxenException

  Deprecated. use `stringValueOf(Object)` instead

  Retrieve a string-value interpretation of this XPath expression when evaluated against the given context.

  The string-value of the expression is determined per the `string(..)` core function as defined in the XPath specification. This means that an expression that selects more than one nodes will return the string value of the first node in the node set..

  Parameters:
    `context` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the string-value of this expression
  Throws:
    `JaxenException` - if an error occurs while attempting to evaluate the expression

### stringValueOf

    public String stringValueOf(Object context)
                         throws JaxenException

  Retrieve a string-value interpretation of this XPath expression when evaluated against the given context.

  The string-value of the expression is determined per the `string(..)` core function as defined in the XPath specification. This means that an expression that selects more than one nodes will return the string value of the first node in the node set..

  Parameters:
    `context` - the node, node-set or Context object for evaluation. This value can be null
  Returns:
    the string-value interpretation of this expression
  Throws:
    `JaxenException` - if an error occurs while attempting to evaluate the expression

### booleanValueOf

    public boolean booleanValueOf(Object context)
                           throws JaxenException

  Retrieve the boolean value of the first node in document order returned by this XPath expression when evaluated in the given context.

  The boolean-value of the expression is determined per the `boolean()` function defined in the XPath specification. This means that an expression that selects zero nodes will return `false`, while an expression that selects one or more nodes will return `true`. An expression that returns a string returns false for empty strings and true for all other strings. An expression that returns a number returns false for zero and true for non-zero numbers.

  Parameters:
    `context` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the boolean-value of this expression
  Throws:
    `JaxenException` - if an error occurs while attempting to evaluate the expression

### numberValueOf

    public Number numberValueOf(Object context)
                         throws JaxenException

  Retrieve the number-value of the first node in document order returned by this XPath expression when evaluated in the given context.

  The number-value of the expression is determined per the `number(..)` core function as defined in the XPath specification. This means that if this expression selects multiple nodes, the number-value of the first node is returned.

  Parameters:
    `context` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the number-value interpretation of this expression
  Throws:
    `JaxenException` - if an error occurs while attempting to evaluate the expression

### selectNodes

    public List selectNodes(Object context)
                     throws JaxenException

  Select all nodes that are selectable by this XPath expression. If multiple nodes match, multiple nodes will be returned.

  NOTE: In most cases, nodes will be returned in document-order, as defined by the XML Canonicalization specification. The exception occurs when using XPath expressions involving the `union` operator (denoted with the pipe '|' character).

  Parameters:
    `context` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the node-set of all items selected by this XPath expression.
  Throws:
    `JaxenException` - if an error occurs while attempting to evaluate the expression
  See Also:
    `selectSingleNode(java.lang.Object)`

### selectSingleNode

    public Object selectSingleNode(Object context)
                            throws JaxenException

  Return the first node in document order that is selected by this XPath expression.

  Parameters:
    `context` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the first node in document order selected by this XPath expression
  Throws:
    `JaxenException` - if an error occurs while attempting to evaluate the expression
  See Also:
    `selectNodes(java.lang.Object)`

### addNamespace

    public void addNamespace(String prefix,
                             String uri)
                      throws JaxenException

  Add a namespace prefix-to-URI mapping for this XPath expression.

  Namespace prefix-to-URI mappings in an XPath are independent of those used within any document. Only the mapping explicitly added to this XPath will be available for resolving the XPath expression.

  This is a convenience method for adding mappings to the default `NamespaceContext` in place for this XPath. If you have installed a specific custom `NamespaceContext`, then this method will throw a `JaxenException`.

  Parameters:
    `prefix` - the namespace prefix
    `uri` - the namespace URI
  Throws:
    `JaxenException` - if a `NamespaceContext` used by this XPath has been explicitly installed

### setNamespaceContext

    public void setNamespaceContext(NamespaceContext namespaceContext)

  Set a `NamespaceContext` for this XPath expression.

  A `NamespaceContext` is responsible for translating namespace prefixes within the expression into namespace URIs.

  Parameters:
    `namespaceContext` - the `NamespaceContext` to install for this expression
  See Also:
    `NamespaceContext`, `NamespaceContext.translateNamespacePrefixToUri(java.lang.String)`

### setFunctionContext

    public void setFunctionContext(FunctionContext functionContext)

  Set a `FunctionContext` for this XPath expression.

  A `FunctionContext` is responsible for resolving all function calls used within the expression.

  Parameters:
    `functionContext` - the `FunctionContext` to install for this expression
  See Also:
    `FunctionContext`, `FunctionContext.getFunction(java.lang.String, java.lang.String, java.lang.String)`

### setVariableContext

    public void setVariableContext(VariableContext variableContext)

  Set a `VariableContext` for this XPath expression.

  A `VariableContext` is responsible for resolving all variables referenced within the expression.

  Parameters:
    `variableContext` - the `VariableContext` to install for this expression.
  See Also:
    `VariableContext`, `VariableContext.getVariableValue(java.lang.String, java.lang.String, java.lang.String)`

### getNamespaceContext

    public NamespaceContext getNamespaceContext()

  Retrieve the `NamespaceContext` used by this XPath expression.

  A `FunctionContext` is responsible for resolving all function calls used within the expression.

  If this XPath expression has not previously had a `NamespaceContext` installed, a new default `NamespaceContext` will be created, installed and returned.

  Returns:
    the `NamespaceContext` used by this expression
  See Also:
    `NamespaceContext`

### getFunctionContext

    public FunctionContext getFunctionContext()

  Retrieve the `FunctionContext` used by this XPath expression.

  A `FunctionContext` is responsible for resolving all function calls used within the expression.

  If this XPath expression has not previously had a `FunctionContext` installed, a new default `FunctionContext` will be created, installed and returned.

  Returns:
    the `FunctionContext` used by this expression
  See Also:
    `FunctionContext`

### getVariableContext

    public VariableContext getVariableContext()

  Retrieve the `VariableContext` used by this XPath expression.

  A `VariableContext` is responsible for resolving all variables referenced within the expression.

  If this XPath expression has not previously had a `VariableContext` installed, a new default `VariableContext` will be created, installed and returned.

  Returns:
    the `VariableContext` used by this expression
  See Also:
    `VariableContext`

### getNavigator

    public Navigator getNavigator()

  Retrieve the XML object-model-specific `Navigator` used to evaluate this XPath expression.

  Returns:
    the implementation-specific `Navigator`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2005 Codehaus. All Rights Reserved.