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
Class BaseXPath

    java.lang.Object
      org.jaxen.BaseXPath

All Implemented Interfaces:
  Serializable, XPath

Direct Known Subclasses:
  Dom4jXPath, DOMXPath, JavaBeanXPath, JDOMXPath, XOMXPath

public class BaseXPath
extends Object
implements XPath, Serializable

Base functionality for all concrete, implementation-specific XPaths.

This class provides generic functionality for further-defined implementation-specific XPaths.

If you want to adapt the Jaxen engine so that it can traverse your own object model, then this is a good base class to derive from. Typically you only really need to provide your own `Navigator` implementation.

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

Constructor Summary
`protected` | `BaseXPath(String xpathExpr)` Construct given an XPath expression string.
`` | `BaseXPath(String xpathExpr, Navigator navigator)` Construct given an XPath expression string.

Method Summary
`void` | `addNamespace(String prefix, String uri)` Add a namespace prefix-to-URI mapping for this XPath expression.
`boolean` | `booleanValueOf(Object node)` Retrieve a boolean-value interpretation of this XPath expression when evaluated against a given context.
`protected FunctionContext` | `createFunctionContext()` Create a default `FunctionContext`.
`protected NamespaceContext` | `createNamespaceContext()` Create a default `NamespaceContext`.
`protected VariableContext` | `createVariableContext()` Create a default `VariableContext`.
`String` | `debug()` Returns a string representation of the parse tree.
`Object` | `evaluate(Object context)` Evaluate this XPath against a given context.
`protected Context` | `getContext(Object node)` Create a `Context` wrapper for the provided implementation-specific object.
`protected ContextSupport` | `getContextSupport()` Retrieve the `ContextSupport` aggregation of `NamespaceContext`, `FunctionContext`, `VariableContext`, and `Navigator`.
`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` for us in evaluating this XPath expression.
`Expr` | `getRootExpr()` Retrieve the root expression of the internal compiled form of this XPath expression.
`VariableContext` | `getVariableContext()` Retrieve the `VariableContext` used by this XPath expression.
`Number` | `numberValueOf(Object node)` Retrieve a number-value interpretation of this XPath expression when evaluated against a given context.
`List` | `selectNodes(Object node)` Select all nodes that are selected by this XPath expression.
`protected List` | `selectNodesForContext(Context context)` Select all nodes that match this XPath expression on the given Context object.
`Object` | `selectSingleNode(Object node)` Select only the first node selected by this XPath expression.
`protected Object` | `selectSingleNodeForContext(Context context)` Return only the first node that is selected by this XPath expression.
`void` | `setFunctionContext(FunctionContext functionContext)` Set a `FunctionContext` for use with this XPath expression.
`void` | `setNamespaceContext(NamespaceContext namespaceContext)` Set a `NamespaceContext` for use with this XPath expression.
`void` | `setVariableContext(VariableContext variableContext)` Set a `VariableContext` for use with this XPath expression.
`String` | `stringValueOf(Object node)` Retrieves the string-value of the result of evaluating this XPath expression when evaluated against the specified context.
`String` | `toString()` Return the original expression text.
`String` | `valueOf(Object node)` Deprecated. replaced by `stringValueOf(java.lang.Object)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### BaseXPath

    protected BaseXPath(String xpathExpr)
                 throws JaxenException

  Construct given an XPath expression string.

Parameters:
  `xpathExpr` - the XPath expression
Throws:
  `JaxenException` - if there is a syntax error while parsing the expression

### BaseXPath

    public BaseXPath(String xpathExpr,
                     Navigator navigator)
              throws JaxenException

  Construct given an XPath expression string.

Parameters:
  `xpathExpr` - the XPath expression
  `navigator` - the XML navigator to use
Throws:
  `JaxenException` - if there is a syntax error while parsing the expression

Method Detail

### evaluate

    public Object evaluate(Object context)
                    throws JaxenException

  Evaluate this XPath against a given context. The context of evaluation may be any object type the navigator recognizes as a node. The return value is either a `String`, `Double`, `Boolean`, or `List` of nodes.

  When using this method, one must be careful to test the class of the returned object. If the returned object is a list, then the items in this list will be the actual `Document`, `Element`, `Attribute`, etc. objects as defined by the concrete XML object-model implementation, directly from the context document. This method does not return copies of anything, but merely returns references to objects within the source document.

  Specified by:
    `evaluate` in interface `XPath`
  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 XPath error occurs during expression evaluation
    `ClassCastException` - if the context is not a node

### selectNodes

    public List selectNodes(Object node)
                     throws JaxenException

  Select all nodes that are selected by this XPath expression. If multiple nodes match, multiple nodes will be returned. Nodes will be returned in document-order, as defined by the XPath specification. If the expression selects a non-node-set (i.e. a number, boolean, or string) then a List containing just that one object is returned.

  Specified by:
    `selectNodes` in interface `XPath`
  Parameters:
    `node` - 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 XPath error occurs during expression evaluation
  See Also:
    `selectNodesForContext(org.jaxen.Context)`

### selectSingleNode

    public Object selectSingleNode(Object node)
                            throws JaxenException

  Select only the first node selected by this XPath expression. If multiple nodes match, only one node will be returned. The selected node will be the first selected node in document-order, as defined by the XPath specification.

  Specified by:
    `selectSingleNode` in interface `XPath`
  Parameters:
    `node` - 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 XPath error occurs during expression evaluation
  See Also:
    `selectNodes(java.lang.Object)`

### valueOf

    public String valueOf(Object node)
                   throws JaxenException

  Deprecated. replaced by `stringValueOf(java.lang.Object)`

  Returns the XPath string-value of the argument node.

  Specified by:
    `valueOf` in interface `XPath`
  Parameters:
    `node` - the node whose value to take
  Returns:
    the XPath string value of this node
  Throws:
    `JaxenException` - if an XPath error occurs during expression evaluation

### stringValueOf

    public String stringValueOf(Object node)
                         throws JaxenException

  Retrieves the string-value of the result of evaluating this XPath expression when evaluated against the specified context.

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

  Specified by:
    `stringValueOf` in interface `XPath`
  Parameters:
    `node` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the string-value of the result of evaluating this expression with the specified context node
  Throws:
    `JaxenException` - if an XPath error occurs during expression evaluation

### booleanValueOf

    public boolean booleanValueOf(Object node)
                           throws JaxenException

  Retrieve a boolean-value interpretation of this XPath expression when evaluated against a 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`.

  Specified by:
    `booleanValueOf` in interface `XPath`
  Parameters:
    `node` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    the boolean-value of the result of evaluating this expression with the specified context node
  Throws:
    `JaxenException` - if an XPath error occurs during expression evaluation

### numberValueOf

    public Number numberValueOf(Object node)
                         throws JaxenException

  Retrieve a number-value interpretation of this XPath expression when evaluated against a 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.

  Specified by:
    `numberValueOf` in interface `XPath`
  Parameters:
    `node` - the node, node-set or Context object for evaluation. This value can be null.
  Returns:
    a `Double` indicating the numeric value of evaluating this expression against the specified context
  Throws:
    `JaxenException` - if an XPath error occurs during expression evaluation

### 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 custom `NamespaceContext` that is not a `SimpleNamespaceContext`, then this method will throw a `JaxenException`.

  Specified by:
    `addNamespace` in interface `XPath`
  Parameters:
    `prefix` - the namespace prefix
    `uri` - the namespace URI
  Throws:
    `JaxenException` - if the `NamespaceContext` used by this XPath is not a `SimpleNamespaceContext`

### setNamespaceContext

    public void setNamespaceContext(NamespaceContext namespaceContext)

  Set a `NamespaceContext` for use with this XPath expression.

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

  Specified by:
    `setNamespaceContext` in interface `XPath`
  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 use with this XPath expression.

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

  Specified by:
    `setFunctionContext` in interface `XPath`
  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 use with this XPath expression.

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

  Specified by:
    `setVariableContext` in interface `XPath`
  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 `NamespaceContext` is responsible for mapping prefixes used within the expression to namespace URIs.

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

  Specified by:
    `getNamespaceContext` in interface `XPath`
  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.

  Specified by:
    `getFunctionContext` in interface `XPath`
  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.

  Specified by:
    `getVariableContext` in interface `XPath`
  Returns:
    the `VariableContext` used by this expression
  See Also:
    `VariableContext`

### getRootExpr

    public Expr getRootExpr()

  Retrieve the root expression of the internal compiled form of this XPath expression.

  Internally, Jaxen maintains a form of Abstract Syntax Tree (AST) to represent the structure of the XPath expression. This is normally not required during normal consumer-grade usage of Jaxen. This method is provided for hard-core users who wish to manipulate or inspect a tree-based version of the expression.

  Returns:
    the root of the AST of this expression

### toString

    public String toString()

  Return the original expression text.

  Returns:
    the normalized XPath expression string

### debug

    public String debug()

  Returns a string representation of the parse tree.

  Returns:
    a string representation of the parse tree.

### getContext

    protected Context getContext(Object node)

  Create a `Context` wrapper for the provided implementation-specific object.

  Parameters:
    `node` - the implementation-specific object to be used as the context
  Returns:
    a `Context` wrapper around the object

### getContextSupport

    protected ContextSupport getContextSupport()

  Retrieve the `ContextSupport` aggregation of `NamespaceContext`, `FunctionContext`, `VariableContext`, and `Navigator`.

  Returns:
    aggregate `ContextSupport` for this XPath expression

### getNavigator

    public Navigator getNavigator()

  Retrieve the XML object-model-specific `Navigator` for us in evaluating this XPath expression.

  Specified by:
    `getNavigator` in interface `XPath`
  Returns:
    the implementation-specific `Navigator`

### createFunctionContext

    protected FunctionContext createFunctionContext()

  Create a default `FunctionContext`.

  Returns:
    a default `FunctionContext`

### createNamespaceContext

    protected NamespaceContext createNamespaceContext()

  Create a default `NamespaceContext`.

  Returns:
    a default `NamespaceContext` instance

### createVariableContext

    protected VariableContext createVariableContext()

  Create a default `VariableContext`.

  Returns:
    a default `VariableContext` instance

### selectNodesForContext

    protected List selectNodesForContext(Context context)
                                  throws JaxenException

  Select all nodes that match this XPath expression on the given Context object. If multiple nodes match, multiple nodes will be returned in document-order, as defined by the XPath specification. If the expression selects a non-node-set (i.e. a number, boolean, or string) then a List containing just that one object is returned.

  Parameters:
    `context` - the Context which gets evaluated
  Returns:
    the node-set of all items selected by this XPath expression
  Throws:
    `JaxenException` - if an XPath error occurs during expression evaluation

### selectSingleNodeForContext

    protected Object selectSingleNodeForContext(Context context)
                                         throws JaxenException

  Return only the first node that is selected by this XPath expression. If multiple nodes match, only one node will be returned. The selected node will be the first selected node in document-order, as defined by the XPath specification. If the XPath expression selects a double, String, or boolean, then that object is returned.

  Parameters:
    `context` - the Context against which this expression is evaluated
  Returns:
    the first node in document order of all nodes selected by this XPath expression
  Throws:
    `JaxenException` - if an XPath error occurs during expression evaluation
  See Also:
    `selectNodesForContext(org.jaxen.Context)`

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.