Class BaseXPath
- java.lang.Object
-
- org.jaxen.BaseXPath
-
- All Implemented Interfaces:
java.io.Serializable,XPath
- Direct Known Subclasses:
Dom4jXPath,DOMXPath,JavaBeanXPath,JDOMXPath,XOMXPath
public class BaseXPath extends java.lang.Object implements XPath, java.io.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
Navigatorimplementation.- Author:
- bob mcwhirter, James Strachan
- See Also:
XPath for dom4j,XPath for JDOM,XPath for W3C DOM, Serialized Form
-
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description voidaddNamespace(java.lang.String prefix, java.lang.String uri)Add a namespace prefix-to-URI mapping for this XPath expression.booleanbooleanValueOf(java.lang.Object node)Retrieve a boolean-value interpretation of this XPath expression when evaluated against a given context.protected FunctionContextcreateFunctionContext()Create a defaultFunctionContext.protected NamespaceContextcreateNamespaceContext()Create a defaultNamespaceContext.protected VariableContextcreateVariableContext()Create a defaultVariableContext.java.lang.Stringdebug()Returns a string representation of the parse tree.java.lang.Objectevaluate(java.lang.Object context)Evaluate this XPath against a given context.protected ContextgetContext(java.lang.Object node)Create aContextwrapper for the provided implementation-specific object.protected ContextSupportgetContextSupport()Retrieve theContextSupportaggregation ofNamespaceContext,FunctionContext,VariableContext, andNavigator.FunctionContextgetFunctionContext()Retrieve theFunctionContextused by this XPath expression.NamespaceContextgetNamespaceContext()Retrieve theNamespaceContextused by this XPath expression.NavigatorgetNavigator()Retrieve the XML object-model-specificNavigatorfor us in evaluating this XPath expression.ExprgetRootExpr()Retrieve the root expression of the internal compiled form of this XPath expression.VariableContextgetVariableContext()Retrieve theVariableContextused by this XPath expression.java.lang.NumbernumberValueOf(java.lang.Object node)Retrieve a number-value interpretation of this XPath expression when evaluated against a given context.java.util.ListselectNodes(java.lang.Object node)Select all nodes that are selected by this XPath expression.protected java.util.ListselectNodesForContext(Context context)Select all nodes that match this XPath expression on the given Context object.java.lang.ObjectselectSingleNode(java.lang.Object node)Select only the first node selected by this XPath expression.protected java.lang.ObjectselectSingleNodeForContext(Context context)Return only the first node that is selected by this XPath expression.voidsetFunctionContext(FunctionContext functionContext)Set aFunctionContextfor use with this XPath expression.voidsetNamespaceContext(NamespaceContext namespaceContext)Set aNamespaceContextfor use with this XPath expression.voidsetVariableContext(VariableContext variableContext)Set aVariableContextfor use with this XPath expression.java.lang.StringstringValueOf(java.lang.Object node)Retrieves the string-value of the result of evaluating this XPath expression when evaluated against the specified context.java.lang.StringtoString()Return the original expression text.java.lang.StringvalueOf(java.lang.Object node)Deprecated.replaced bystringValueOf(java.lang.Object)
-
-
-
Constructor Detail
-
BaseXPath
protected BaseXPath(java.lang.String xpathExpr) throws JaxenExceptionConstruct 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(java.lang.String xpathExpr, Navigator navigator) throws JaxenExceptionConstruct given an XPath expression string.- Parameters:
xpathExpr- the XPath expressionnavigator- the XML navigator to use- Throws:
JaxenException- if there is a syntax error while parsing the expression
-
-
Method Detail
-
evaluate
public java.lang.Object evaluate(java.lang.Object context) throws JaxenExceptionEvaluate 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 aString,Double,Boolean, orListof 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.- Specified by:
evaluatein interfaceXPath- 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 evaluationjava.lang.ClassCastException- if the context is not a node
-
selectNodes
public java.util.List selectNodes(java.lang.Object node) throws JaxenExceptionSelect 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.- Specified by:
selectNodesin interfaceXPath- 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:
selectNodesForContext(org.jaxen.Context)
-
selectSingleNode
public java.lang.Object selectSingleNode(java.lang.Object node) throws JaxenExceptionSelect 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.- Specified by:
selectSingleNodein interfaceXPath- 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:
selectNodes(java.lang.Object)
-
valueOf
public java.lang.String valueOf(java.lang.Object node) throws JaxenExceptionDeprecated.replaced bystringValueOf(java.lang.Object)Returns the XPath string-value of the argument node.- Specified by:
valueOfin interfaceXPath- 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
-
stringValueOf
public java.lang.String stringValueOf(java.lang.Object node) throws JaxenExceptionRetrieves 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.- Specified by:
stringValueOfin interfaceXPath- 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
-
booleanValueOf
public boolean booleanValueOf(java.lang.Object node) throws JaxenExceptionRetrieve 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 returnfalse, while an expression that selects one or more nodes will returntrue.- Specified by:
booleanValueOfin interfaceXPath- 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
-
numberValueOf
public java.lang.Number numberValueOf(java.lang.Object node) throws JaxenExceptionRetrieve 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.- Specified by:
numberValueOfin interfaceXPath- Parameters:
node- the node, node-set or Context object for evaluation. This value can be null.- Returns:
- a
Doubleindicating the numeric value of evaluating this expression against the specified context - Throws:
JaxenException- if an XPath error occurs during expression evaluation
-
addNamespace
public void addNamespace(java.lang.String prefix, java.lang.String uri) throws JaxenExceptionAdd 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
NamespaceContextin place for this XPath. If you have installed a customNamespaceContextthat is not aSimpleNamespaceContext, then this method will throw aJaxenException.- Specified by:
addNamespacein interfaceXPath- Parameters:
prefix- the namespace prefixuri- the namespace URI- Throws:
JaxenException- if theNamespaceContextused by this XPath is not aSimpleNamespaceContext
-
setNamespaceContext
public void setNamespaceContext(NamespaceContext namespaceContext)
Set aNamespaceContextfor use with this XPath expression.A
NamespaceContextis responsible for translating namespace prefixes within the expression into namespace URIs.- Specified by:
setNamespaceContextin interfaceXPath- Parameters:
namespaceContext- theNamespaceContextto install for this expression- See Also:
NamespaceContext,NamespaceContext.translateNamespacePrefixToUri(java.lang.String)
-
setFunctionContext
public void setFunctionContext(FunctionContext functionContext)
Set aFunctionContextfor use with this XPath expression.A
FunctionContextis responsible for resolving all function calls used within the expression.- Specified by:
setFunctionContextin interfaceXPath- Parameters:
functionContext- theFunctionContextto install for this expression- See Also:
FunctionContext,FunctionContext.getFunction(java.lang.String, java.lang.String, java.lang.String)
-
setVariableContext
public void setVariableContext(VariableContext variableContext)
Set aVariableContextfor use with this XPath expression.A
VariableContextis responsible for resolving all variables referenced within the expression.- Specified by:
setVariableContextin interfaceXPath- Parameters:
variableContext- TheVariableContextto install for this expression- See Also:
VariableContext,VariableContext.getVariableValue(java.lang.String, java.lang.String, java.lang.String)
-
getNamespaceContext
public NamespaceContext getNamespaceContext()
Retrieve theNamespaceContextused by this XPath expression.A
NamespaceContextis responsible for mapping prefixes used within the expression to namespace URIs.If this XPath expression has not previously had a
NamespaceContextinstalled, a new defaultNamespaceContextwill be created, installed and returned.- Specified by:
getNamespaceContextin interfaceXPath- Returns:
- the
NamespaceContextused by this expression - See Also:
NamespaceContext
-
getFunctionContext
public FunctionContext getFunctionContext()
Retrieve theFunctionContextused by this XPath expression.A
FunctionContextis responsible for resolving all function calls used within the expression.If this XPath expression has not previously had a
FunctionContextinstalled, a new defaultFunctionContextwill be created, installed and returned.- Specified by:
getFunctionContextin interfaceXPath- Returns:
- the
FunctionContextused by this expression - See Also:
FunctionContext
-
getVariableContext
public VariableContext getVariableContext()
Retrieve theVariableContextused by this XPath expression.A
VariableContextis responsible for resolving all variables referenced within the expression.If this XPath expression has not previously had a
VariableContextinstalled, a new defaultVariableContextwill be created, installed and returned.- Specified by:
getVariableContextin interfaceXPath- Returns:
- the
VariableContextused by this expression - See Also:
VariableContext
-
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
-
toString
public java.lang.String toString()
Return the original expression text.- Overrides:
toStringin classjava.lang.Object- Returns:
- the normalized XPath expression string
-
debug
public java.lang.String debug()
Returns a string representation of the parse tree.- Returns:
- a string representation of the parse tree.
-
getContext
protected Context getContext(java.lang.Object node)
Create aContextwrapper for the provided implementation-specific object.- Parameters:
node- the implementation-specific object to be used as the context- Returns:
- a
Contextwrapper around the object
-
getContextSupport
protected ContextSupport getContextSupport()
Retrieve theContextSupportaggregation ofNamespaceContext,FunctionContext,VariableContext, andNavigator.- Returns:
- aggregate
ContextSupportfor this XPath expression
-
getNavigator
public Navigator getNavigator()
Retrieve the XML object-model-specificNavigatorfor us in evaluating this XPath expression.- Specified by:
getNavigatorin interfaceXPath- Returns:
- the implementation-specific
Navigator
-
createFunctionContext
protected FunctionContext createFunctionContext()
Create a defaultFunctionContext.- Returns:
- a default
FunctionContext
-
createNamespaceContext
protected NamespaceContext createNamespaceContext()
Create a defaultNamespaceContext.- Returns:
- a default
NamespaceContextinstance
-
createVariableContext
protected VariableContext createVariableContext()
Create a defaultVariableContext.- Returns:
- a default
VariableContextinstance
-
selectNodesForContext
protected java.util.List selectNodesForContext(Context context) throws JaxenException
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
-
selectSingleNodeForContext
protected java.lang.Object selectSingleNodeForContext(Context context) throws JaxenException
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:
selectNodesForContext(org.jaxen.Context)
-
-