org.jaxen
public interface XPath
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.
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 {@link 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) Retrieve a string-value interpretation of this XPath
expression when evaluated against the given context.
|
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 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
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
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
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
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
Returns: the implementation-specific Navigator
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
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
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: XPath
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: XPath
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
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
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
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
Deprecated: use {@link #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