org.jaxen

Class BaseXPath

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 {@link org.jaxen.Navigator} implementation.

Author: bob mcwhirter James Strachan

See Also: XPath for dom4j XPath for JDOM XPath for W3C DOM

Field Summary
StringexprText
Original expression text.
Navigatornavigator
the implementation-specific Navigator for retrieving XML nodes *
ContextSupportsupport
the support information and function, namespace and variable contexts
XPathExprxpath
the parsed form of the XPath expression
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
voidaddNamespace(String prefix, String uri)
Add a namespace prefix-to-URI mapping for this XPath expression.
booleanbooleanValueOf(Object node)
Retrieve a boolean-value interpretation of this XPath expression when evaluated against a given context.
protected FunctionContextcreateFunctionContext()
Create a default FunctionContext.
protected NamespaceContextcreateNamespaceContext()
Create a default NamespaceContext.
protected VariableContextcreateVariableContext()
Create a default VariableContext.
Stringdebug()
Returns a string representation of the parse tree.
Objectevaluate(Object context)
Evaluate this XPath against a given context.
protected ContextgetContext(Object node)
Create a {@link Context} wrapper for the provided implementation-specific object.
protected ContextSupportgetContextSupport()
Retrieve the {@link ContextSupport} aggregation of NamespaceContext, FunctionContext, VariableContext, and {@link Navigator}.
FunctionContextgetFunctionContext()
Retrieve the FunctionContext used by this XPath expression.
NamespaceContextgetNamespaceContext()
Retrieve the NamespaceContext used by this XPath expression.
NavigatorgetNavigator()
Retrieve the XML object-model-specific {@link Navigator} for us in evaluating this XPath expression.
ExprgetRootExpr()
Retrieve the root expression of the internal compiled form of this XPath expression.
VariableContextgetVariableContext()
Retrieve the VariableContext used by this XPath expression.
NumbernumberValueOf(Object node)
Retrieve a number-value interpretation of this XPath expression when evaluated against a given context.
ListselectNodes(Object node)
Select all nodes that are selected by this XPath expression.
protected ListselectNodesForContext(Context context)
Select all nodes that match this XPath expression on the given Context object.
ObjectselectSingleNode(Object node)
Select only the first node selected by this XPath expression.
protected ObjectselectSingleNodeForContext(Context context)
Return only the first node that is selected by this XPath expression.
voidsetFunctionContext(FunctionContext functionContext)
Set a FunctionContext for use with this XPath expression.
voidsetNamespaceContext(NamespaceContext namespaceContext)
Set a NamespaceContext for use with this XPath expression.
voidsetVariableContext(VariableContext variableContext)
Set a VariableContext for use with this XPath expression.
StringstringValueOf(Object node)
Retrieves the string-value of the result of evaluating this XPath expression when evaluated against the specified context.
StringtoString()
Return the original expression text.
StringvalueOf(Object node)
Returns the XPath string-value of the argument node.

Field Detail

exprText

private String exprText
Original expression text.

navigator

private Navigator navigator
the implementation-specific Navigator for retrieving XML nodes *

support

private ContextSupport support
the support information and function, namespace and variable contexts

xpath

private XPathExpr xpath
the parsed form of the XPath expression

Constructor Detail

BaseXPath

protected BaseXPath(String xpathExpr)
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)
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

addNamespace

public void addNamespace(String prefix, String uri)
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 {@link 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.

Parameters: prefix the namespace prefix uri the namespace URI

Throws: JaxenException if the NamespaceContext used by this XPath is not a SimpleNamespaceContext

booleanValueOf

public boolean booleanValueOf(Object node)
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.

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

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

debug

public String debug()
Returns a string representation of the parse tree.

Returns: a string representation of the parse tree.

evaluate

public Object evaluate(Object context)
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.

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

getContext

protected Context getContext(Object node)
Create a {@link 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 {@link ContextSupport} aggregation of NamespaceContext, FunctionContext, VariableContext, and {@link Navigator}.

Returns: aggregate ContextSupport for this XPath expression

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

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.

Returns: the NamespaceContext used by this expression

See Also: NamespaceContext

getNavigator

public Navigator getNavigator()
Retrieve the XML object-model-specific {@link Navigator} for us in evaluating this XPath expression.

Returns: the implementation-specific Navigator

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

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

numberValueOf

public Number numberValueOf(Object node)
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.

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

selectNodes

public List selectNodes(Object node)
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.

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

selectNodesForContext

protected List selectNodesForContext(Context context)
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

selectSingleNode

public Object selectSingleNode(Object node)
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.

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

selectSingleNodeForContext

protected Object selectSingleNodeForContext(Context context)
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: BaseXPath

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.

Parameters: functionContext the FunctionContext to install for this expression

See Also: FunctionContext FunctionContext

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.

Parameters: namespaceContext the NamespaceContext to install for this expression

See Also: NamespaceContext NamespaceContext

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.

Parameters: variableContext The VariableContext to install for this expression

See Also: VariableContext VariableContext

stringValueOf

public String stringValueOf(Object node)
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.

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

toString

public String toString()
Return the original expression text.

Returns: the normalized XPath expression string

valueOf

public String valueOf(Object node)

Deprecated: replaced by {@link #stringValueOf}

Returns the XPath string-value of the argument node.

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