org.jaxen

Interface XPath

All Known Implementing Classes:

BaseXPath, Dom4jXPath, DOMXPath, JavaBeanXPath, JDOMXPath, XOMXPath

public interface XPath

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

Methods

Modifier and Type	Method and Description
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Navigator getNavigator()

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

Returns:

the implementation-specific Navigator