Class BaseXPath

java.lang.Object
org.jaxen.BaseXPath
All Implemented Interfaces:
Serializable, XPath
Direct Known Subclasses:
Dom4jXPath, DOMXPath, JavaBeanXPath, JDOMXPath
public class BaseXPath extends Object implements XPath, 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 to traverse your own object model, then this is a good base class to derive from. Typically you only really need to provide your own Navigator implementation.

See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      See Also:

    • exprText

      private final String exprText
      Original expression text.

    • xpath

      private final XPathExpr xpath
      the parsed form of the XPath expression

    • support

      private ContextSupport support
      the support information and function, namespace and variable contexts

  • Constructor Details

    • BaseXPath

      protected BaseXPath(String xpathExpr) throws JaxenException
      Construct 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(String xpathExpr, Navigator navigator) throws JaxenException
      Construct given an XPath expression string.
      Parameters:
      xpathExpr - the XPath expression
      navigator - the XML navigator to use
      Throws:
      JaxenException - if there is a syntax error while parsing the expression

  • Method Details

    • evaluate

      public Object evaluate(Object context) throws JaxenException
      Evaluate 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 a String, Double, Boolean, or List of 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:
      evaluate in interface XPath
      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 evaluation
      ClassCastException - if the context is not a node

    • selectNodes

      public List selectNodes(Object node) throws JaxenException
      List all the nodes selected by this XPath expression. If multiple nodes match, multiple nodes are returned. Nodes are 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:
      selectNodes in interface XPath
      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:

    • selectSingleNode

      public Object selectSingleNode(Object node) throws JaxenException
      Return the first node selected by this XPath expression. If multiple nodes match, only one node is returned. The selected node will be the first selected node in document-order, as defined by the XPath specification.
      Specified by:
      selectSingleNode in interface XPath
      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:

    • valueOf

      public String valueOf(Object node) throws JaxenException
      Deprecated.
      replaced by stringValueOf(Object)
      Returns the XPath string-value of the argument node.
      Specified by:
      valueOf in interface XPath
      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 String stringValueOf(Object node) throws JaxenException
      Retrieves 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:
      stringValueOf in interface XPath
      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(Object node) throws JaxenException
      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(..) 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.

      Specified by:
      booleanValueOf in interface XPath
      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 Number numberValueOf(Object node) throws JaxenException
      Retrieve 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:
      numberValueOf in interface XPath
      Parameters:
      node - the node, node-set or Context object for evaluation. This value can be null.
      Returns:
      a Double indicating 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(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 custom NamespaceContext that is not a SimpleNamespaceContext, then this method will throw a JaxenException.

      Specified by:
      addNamespace in interface XPath
      Parameters:
      prefix - the namespace prefix
      uri - the namespace URI
      Throws:
      JaxenException - if the NamespaceContext used by this XPath is not a SimpleNamespaceContext

    • setNamespaceContext

      public void setNamespaceContext(NamespaceContext namespaceContext)
      Set a NamespaceContext for use with this XPath expression.

      A NamespaceContext is responsible for translating namespace prefixes within the expression into namespace URIs.

      Specified by:
      setNamespaceContext in interface XPath
      Parameters:
      namespaceContext - the NamespaceContext to install for this expression
      See Also:

    • setFunctionContext

      public void setFunctionContext(FunctionContext functionContext)
      Set a FunctionContext for use with this XPath expression.

      A FunctionContext is responsible for resolving all function calls used within the expression.

      Specified by:
      setFunctionContext in interface XPath
      Parameters:
      functionContext - the FunctionContext to install for this expression
      See Also:

    • setVariableContext

      public void setVariableContext(VariableContext variableContext)
      Set a VariableContext for use with this XPath expression.

      A VariableContext is responsible for resolving all variables referenced within the expression.

      Specified by:
      setVariableContext in interface XPath
      Parameters:
      variableContext - The VariableContext to install for this expression
      See Also:

    • getNamespaceContext

      public NamespaceContext getNamespaceContext()
      Retrieve the NamespaceContext used by this XPath expression.

      A NamespaceContext is responsible for mapping prefixes used within the expression to namespace URIs.

      If this XPath expression has not previously had a NamespaceContext installed, a new default NamespaceContext will be created, installed and returned.

      Specified by:
      getNamespaceContext in interface XPath
      Returns:
      the NamespaceContext used by this expression
      See Also:

    • getFunctionContext

      public 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.

      Specified by:
      getFunctionContext in interface XPath
      Returns:
      the FunctionContext used by this expression
      See Also:

    • getVariableContext

      public 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.

      Specified by:
      getVariableContext in interface XPath
      Returns:
      the VariableContext used by this expression
      See Also:

    • 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 String toString()
      Return the original expression text.
      Overrides:
      toString in class Object
      Returns:
      the normalized XPath expression string

    • debug

      public String debug()
      Returns a string representation of the parse tree.
      Returns:
      a string representation of the parse tree.

    • getContext

      protected Context getContext(Object node)
      Create a Context wrapper for the provided implementation-specific object.
      Parameters:
      node - the implementation-specific object to be used as the context
      Returns:
      a Context wrapper around the object

    • getContextSupport

      protected ContextSupport getContextSupport()
      Retrieve the ContextSupport aggregation of NamespaceContext, FunctionContext, VariableContext, and Navigator.
      Returns:
      aggregate ContextSupport for this XPath expression

    • getNavigator

      public Navigator getNavigator()
      Retrieve the XML object-model-specific Navigator for us in evaluating this XPath expression.
      Specified by:
      getNavigator in interface XPath
      Returns:
      the implementation-specific Navigator

    • createFunctionContext

      protected FunctionContext createFunctionContext()
      Create a default FunctionContext.
      Returns:
      a default FunctionContext

    • createNamespaceContext

      protected NamespaceContext createNamespaceContext()
      Create a default NamespaceContext.
      Returns:
      a default NamespaceContext instance

    • createVariableContext

      protected VariableContext createVariableContext()
      Create a default VariableContext.
      Returns:
      a default VariableContext instance

    • selectNodesForContext

      protected 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 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: