org.dom4j

Interface XPath

public interface XPath extends NodeFilter

XPath represents an XPath expression after it has been parsed from a String.

Version: $Revision: 1.20 $

Author: James Strachan

Method Summary
booleanbooleanValueOf(Object context)
Retrieve a boolean-value interpretation of this XPath expression when evaluated against a given context.
Objectevaluate(Object context)

evaluate evaluates an XPath expression and returns the result as an {@link Object}.

FunctionContextgetFunctionContext()
DOCUMENT ME!
NamespaceContextgetNamespaceContext()
DOCUMENT ME!
StringgetText()

getText will return the textual version of the XPath expression.

VariableContextgetVariableContext()
DOCUMENT ME!
booleanmatches(Node node)

matches returns true if the given node matches the XPath expression.

NumbernumberValueOf(Object context)

numberValueOf evaluates an XPath expression and returns the numeric value of the XPath expression if the XPath expression results is a number, or null if the result is not a number.

ListselectNodes(Object context)

selectNodes performs this XPath expression on the given {@link Node}or {@link List}of {@link Node}s instances appending all the results together into a single list.

ListselectNodes(Object context, XPath sortXPath)

selectNodes evaluates the XPath expression on the given {@link Node}or {@link List}of {@link Node}s and returns the result as a List of Node s sorted by the sort XPath expression.

ListselectNodes(Object context, XPath sortXPath, boolean distinct)

selectNodes evaluates the XPath expression on the given {@link Node}or {@link List}of {@link Node}s and returns the result as a List of Node s sorted by the sort XPath expression.

ObjectselectObject(Object context)

selectObject evaluates an XPath expression and returns the result as an {@link Object}.

NodeselectSingleNode(Object context)

selectSingleNode evaluates this XPath expression on the given {@link Node}or {@link List}of {@link Node}s and returns the result as a single Node instance.

voidsetFunctionContext(FunctionContext functionContext)
Sets the function context to be used when evaluating XPath expressions
voidsetNamespaceContext(NamespaceContext namespaceContext)
Sets the namespace context to be used when evaluating XPath expressions
voidsetNamespaceURIs(Map map)

Sets the current NamespaceContext from a Map where the keys are the String namespace prefixes and the values are the namespace URIs.

voidsetVariableContext(VariableContext variableContext)
Sets the variable context to be used when evaluating XPath expressions
voidsort(List list)

sort sorts the given List of Nodes using this XPath expression as a {@link java.util.Comparator}.

voidsort(List list, boolean distinct)

sort sorts the given List of Nodes using this XPath expression as a {@link java.util.Comparator}and optionally removing duplicates.

StringvalueOf(Object context)

valueOf evaluates this XPath expression and returns the textual representation of the results using the XPath string() function.

Method Detail

booleanValueOf

public boolean booleanValueOf(Object context)
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(..) core function as 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: context The node, nodeset or Context object for evaluation. This value can be null

Returns: The boolean-value interpretation of this expression.

Since: 1.5

evaluate

public Object evaluate(Object context)

evaluate evaluates an XPath expression and returns the result as an {@link Object}. The object returned can either be a {@link List} of {@link Node}instances, a {@link Node}instance, a {@link String} or a {@link Number}instance depending on the XPath expression.

Parameters: context is either a node or a list of nodes on which to evalute the XPath

Returns: the value of the XPath expression as a {@link List}of {@link Node} instances, a {@link Node}instance, a {@link String}or a {@link Number}instance depending on the XPath expression.

getFunctionContext

public FunctionContext getFunctionContext()
DOCUMENT ME!

Returns: the current function context

getNamespaceContext

public NamespaceContext getNamespaceContext()
DOCUMENT ME!

Returns: the current namespace context

getText

public String getText()

getText will return the textual version of the XPath expression.

Returns: the textual format of the XPath expression.

getVariableContext

public VariableContext getVariableContext()
DOCUMENT ME!

Returns: the current variable context

matches

public boolean matches(Node node)

matches returns true if the given node matches the XPath expression. To be more precise when evaluating this XPath expression on the given node the result set must include the node.

Parameters: node DOCUMENT ME!

Returns: true if the given node matches this XPath expression

numberValueOf

public Number numberValueOf(Object context)

numberValueOf evaluates an XPath expression and returns the numeric value of the XPath expression if the XPath expression results is a number, or null if the result is not a number.

Parameters: context is either a node or a list of nodes on which to evalute the XPath

Returns: the numeric result of the XPath expression or null if the result is not a number.

selectNodes

public List selectNodes(Object context)

selectNodes performs this XPath expression on the given {@link Node}or {@link List}of {@link Node}s instances appending all the results together into a single list.

Parameters: context is either a node or a list of nodes on which to evalute the XPath

Returns: the results of all the XPath evaluations as a single list

selectNodes

public List selectNodes(Object context, XPath sortXPath)

selectNodes evaluates the XPath expression on the given {@link Node}or {@link List}of {@link Node}s and returns the result as a List of Node s sorted by the sort XPath expression.

Parameters: context is either a node or a list of nodes on which to evalute the XPath sortXPath is the XPath expression to sort by

Returns: a list of Node instances

selectNodes

public List selectNodes(Object context, XPath sortXPath, boolean distinct)

selectNodes evaluates the XPath expression on the given {@link Node}or {@link List}of {@link Node}s and returns the result as a List of Node s sorted by the sort XPath expression.

Parameters: context is either a node or a list of nodes on which to evalute the XPath sortXPath is the XPath expression to sort by distinct specifies whether or not duplicate values of the sort expression are allowed. If this parameter is true then only distinct sort expressions values are included in the result

Returns: a list of Node instances

selectObject

public Object selectObject(Object context)

Deprecated: please use evaluate(Object) instead. WILL BE REMOVED IN dom4j-1.6 !!

selectObject evaluates an XPath expression and returns the result as an {@link Object}. The object returned can either be a {@link List} of {@link Node}instances, a {@link Node}instance, a {@link String} or a {@link Number}instance depending on the XPath expression.

Parameters: context is either a node or a list of nodes on which to evalute the XPath

Returns: the value of the XPath expression as a {@link List}of {@link Node} instances, a {@link Node}instance, a {@link String}or a {@link Number}instance depending on the XPath expression.

selectSingleNode

public Node selectSingleNode(Object context)

selectSingleNode evaluates this XPath expression on the given {@link Node}or {@link List}of {@link Node}s and returns the result as a single Node instance.

Parameters: context is either a node or a list of nodes on which to evalute the XPath

Returns: a single matching Node instance

setFunctionContext

public void setFunctionContext(FunctionContext functionContext)
Sets the function context to be used when evaluating XPath expressions

Parameters: functionContext DOCUMENT ME!

setNamespaceContext

public void setNamespaceContext(NamespaceContext namespaceContext)
Sets the namespace context to be used when evaluating XPath expressions

Parameters: namespaceContext DOCUMENT ME!

setNamespaceURIs

public void setNamespaceURIs(Map map)

Sets the current NamespaceContext from a Map where the keys are the String namespace prefixes and the values are the namespace URIs.

For example:

 Map uris = new HashMap();
 uris.put("SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/");
 uris.put("m", "urn:xmethodsBabelFish");
 XPath xpath = document
         .createXPath("SOAP-ENV:Envelope/SOAP-ENV:Body/m:BabelFish");
 xpath.setNamespaceURIs(uris);
 Node babelfish = xpath.selectSingleNode(document);
 

Parameters: map the map containing the namespace mappings

setVariableContext

public void setVariableContext(VariableContext variableContext)
Sets the variable context to be used when evaluating XPath expressions

Parameters: variableContext DOCUMENT ME!

sort

public void sort(List list)

sort sorts the given List of Nodes using this XPath expression as a {@link java.util.Comparator}.

Parameters: list is the list of Nodes to sort

sort

public void sort(List list, boolean distinct)

sort sorts the given List of Nodes using this XPath expression as a {@link java.util.Comparator}and optionally removing duplicates.

Parameters: list is the list of Nodes to sort distinct if true then duplicate values (using the sortXPath for comparisions) will be removed from the List

valueOf

public String valueOf(Object context)

valueOf evaluates this XPath expression and returns the textual representation of the results using the XPath string() function.

Parameters: context is either a node or a list of nodes on which to evalute the XPath

Returns: the string representation of the results of the XPath expression

Copyright B) 2005 MetaStuff Ltd. All Rights Reserved. Hosted by

SourceForge