Interface XPath
-
- All Known Implementing Classes:
BaseXPath
,Dom4jXPath
,DOMXPath
,JavaBeanXPath
,JDOMXPath
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 JaxenContext
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
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description void
addNamespace(java.lang.String prefix, java.lang.String uri)
Add a namespace prefix-to-URI mapping for this XPath expression.boolean
booleanValueOf(java.lang.Object context)
Retrieve the boolean value of the first node in document order returned by this XPath expression when evaluated in the given context.java.lang.Object
evaluate(java.lang.Object context)
Evaluate this XPath against the given context.FunctionContext
getFunctionContext()
Retrieve theFunctionContext
used by this XPath expression.NamespaceContext
getNamespaceContext()
Retrieve theNamespaceContext
used by this XPath expression.Navigator
getNavigator()
Retrieve the XML object-model-specificNavigator
used to evaluate this XPath expression.VariableContext
getVariableContext()
Retrieve theVariableContext
used by this XPath expression.java.lang.Number
numberValueOf(java.lang.Object context)
Retrieve the number-value of the first node in document order returned by this XPath expression when evaluated in the given context.java.util.List
selectNodes(java.lang.Object context)
Select all nodes that are selectable by this XPath expression.java.lang.Object
selectSingleNode(java.lang.Object context)
Return the first node in document order that is selected by this XPath expression.void
setFunctionContext(FunctionContext functionContext)
Set aFunctionContext
for this XPath expression.void
setNamespaceContext(NamespaceContext namespaceContext)
Set aNamespaceContext
for this XPath expression.void
setVariableContext(VariableContext variableContext)
Set aVariableContext
for this XPath expression.java.lang.String
stringValueOf(java.lang.Object context)
Retrieve a string-value interpretation of this XPath expression when evaluated against the given context.java.lang.String
valueOf(java.lang.Object context)
Deprecated.usestringValueOf(Object)
instead
-
-
-
Method Detail
-
evaluate
java.lang.Object evaluate(java.lang.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 actualDocument
,Element
orAttribute
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
java.lang.String valueOf(java.lang.Object context) throws JaxenException
Deprecated.usestringValueOf(Object)
insteadRetrieve 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
java.lang.String stringValueOf(java.lang.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(java.lang.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 returnfalse
, while an expression that selects one or more nodes will returntrue
. 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
java.lang.Number numberValueOf(java.lang.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
java.util.List selectNodes(java.lang.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
java.lang.Object selectSingleNode(java.lang.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(java.lang.String prefix, java.lang.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 customNamespaceContext
, then this method will throw aJaxenException
.- Parameters:
prefix
- the namespace prefixuri
- the namespace URI- Throws:
JaxenException
- if aNamespaceContext
used by this XPath has been explicitly installed
-
setNamespaceContext
void setNamespaceContext(NamespaceContext namespaceContext)
Set aNamespaceContext
for this XPath expression.A
NamespaceContext
is responsible for translating namespace prefixes within the expression into namespace URIs.- Parameters:
namespaceContext
- theNamespaceContext
to install for this expression- See Also:
NamespaceContext
,NamespaceContext.translateNamespacePrefixToUri(java.lang.String)
-
setFunctionContext
void setFunctionContext(FunctionContext functionContext)
Set aFunctionContext
for this XPath expression.A
FunctionContext
is responsible for resolving all function calls used within the expression.- Parameters:
functionContext
- theFunctionContext
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 aVariableContext
for this XPath expression.A
VariableContext
is responsible for resolving all variables referenced within the expression.- Parameters:
variableContext
- theVariableContext
to install for this expression.- See Also:
VariableContext
,VariableContext.getVariableValue(java.lang.String, java.lang.String, java.lang.String)
-
getNamespaceContext
NamespaceContext getNamespaceContext()
Retrieve theNamespaceContext
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 defaultNamespaceContext
will be created, installed and returned.- Returns:
- the
NamespaceContext
used by this expression - See Also:
NamespaceContext
-
getFunctionContext
FunctionContext getFunctionContext()
Retrieve theFunctionContext
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 defaultFunctionContext
will be created, installed and returned.- Returns:
- the
FunctionContext
used by this expression - See Also:
FunctionContext
-
getVariableContext
VariableContext getVariableContext()
Retrieve theVariableContext
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 defaultVariableContext
will be created, installed and returned.- Returns:
- the
VariableContext
used by this expression - See Also:
VariableContext
-
-