Coverage Report - org.jaxen.XPath
 
Classes in this File Line Coverage Branch Coverage Complexity
XPath
N/A
N/A
1
 
 1  
 package org.jaxen;
 2  
 
 3  
 /*
 4  
  $Id: XPath.java,v 1.13 2007/05/02 15:00:13 elharo Exp $
 5  
 
 6  
  Copyright 2003 The Werken Company. All Rights Reserved.
 7  
  
 8  
 Redistribution and use in source and binary forms, with or without
 9  
 modification, are permitted provided that the following conditions are
 10  
 met:
 11  
 
 12  
   * Redistributions of source code must retain the above copyright
 13  
     notice, this list of conditions and the following disclaimer.
 14  
 
 15  
   * Redistributions in binary form must reproduce the above copyright
 16  
     notice, this list of conditions and the following disclaimer in the
 17  
     documentation and/or other materials provided with the distribution.
 18  
 
 19  
   * Neither the name of the Jaxen Project nor the names of its
 20  
     contributors may be used to endorse or promote products derived 
 21  
     from this software without specific prior written permission.
 22  
 
 23  
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 24  
 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 25  
 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 26  
 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
 27  
 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 28  
 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 29  
 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 30  
 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 31  
 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 32  
 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 33  
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 34  
 
 35  
  */
 36  
 
 37  
 import java.util.List;
 38  
 
 39  
 /** Represents an XPath 1.0 expression which
 40  
  *  can be evaluated against a variety of different XML object models.
 41  
  *
 42  
  *  <p>
 43  
  *  Most of the evaluation methods take a context object. This is typically a
 44  
  *  node or node-set object (which is typically a <code>List</code>
 45  
  *  of node objects) or a Jaxen <code>Context</code> object.
 46  
  *  A null context is allowed, meaning that 
 47  
  *  there are no XML nodes on which to evaluate.
 48  
  *  </p>
 49  
  *
 50  
  *  @see org.jaxen.dom4j.Dom4jXPath XPath for dom4j
 51  
  *  @see org.jaxen.jdom.JDOMXPath  XPath for JDOM
 52  
  *  @see org.jaxen.dom.DOMXPath   XPath for W3C DOM
 53  
  *
 54  
  *  @author <a href="mailto:bob@eng.werken.com">bob mcwhirter</a>
 55  
  *  @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
 56  
  */
 57  
 public interface XPath
 58  
 {
 59  
     // ----------------------------------------------------------------------
 60  
     //     Basic Evaluation
 61  
     // ----------------------------------------------------------------------
 62  
 
 63  
     /** Evaluate this XPath against the given context.
 64  
      *
 65  
      *  <p>
 66  
      *  The context of evaluation my be a <em>document</em>,
 67  
      *  an <em>element</em>, or a set of <em>elements</em>.
 68  
      *  </p>
 69  
      *
 70  
      *  <p>
 71  
      *  If the expression evaluates to an XPath string, number, or boolean
 72  
      *  type, then the equivalent Java object type is returned.  
 73  
      *  Otherwise, if the result is a node-set, then the returned value is a
 74  
      *  <code>List</code>.
 75  
      *  </p>
 76  
      *
 77  
      *  <p>
 78  
      *  When using this method, one must be careful to
 79  
      *  test the class of the returned objects, and of 
 80  
      *  each of the composite members if a <code>List</code>
 81  
      *  is returned.  If the returned members are XML nodes,
 82  
      *  they will be the actual <code>Document</code>,
 83  
      *  <code>Element</code> or <code>Attribute</code> objects
 84  
      *  as defined by the concrete XML object-model implementation,
 85  
      *  directly from the context document.  This method <strong>does not
 86  
      *  return <em>copies</em> of anything</strong>. It merely returns
 87  
      *  references to nodes within the source document.
 88  
      *  </p>
 89  
      *  
 90  
      *  @param context the node, node-set or Context object for evaluation. 
 91  
      *         This value can be null.
 92  
      *
 93  
      *  @return the result of evaluating the XPath expression
 94  
      *          against the supplied context
 95  
      *
 96  
      *  @throws JaxenException if an error occurs while attempting
 97  
      *          to evaluate the expression
 98  
      */
 99  
     Object evaluate(Object context) throws JaxenException;
 100  
     
 101  
     // ----------------------------------------------------------------------
 102  
     //     Advanced Evaluation
 103  
     // ----------------------------------------------------------------------
 104  
     
 105  
     /** Retrieve a string-value interpretation of this XPath
 106  
      *  expression when evaluated against the given context.
 107  
      *
 108  
      *  <p>
 109  
      *  The string-value of the expression is determined per
 110  
      *  the <code>string(..)</code> core function as defined
 111  
      *  in the XPath specification.  This means that an expression
 112  
      *  that selects more than one nodes will return the string value
 113  
      *  of the first node in the node set..
 114  
      *  </p>
 115  
      *
 116  
      *  @deprecated use {@link #stringValueOf(Object)} instead
 117  
      *
 118  
      *  @param context the node, node-set or Context object for evaluation. 
 119  
      *         This value can be null.
 120  
      *
 121  
      *  @return the string-value of this expression
 122  
      *
 123  
      *  @throws JaxenException if an error occurs while attempting
 124  
      *          to evaluate the expression
 125  
      */
 126  
     String valueOf(Object context)
 127  
         throws JaxenException;
 128  
 
 129  
     /** Retrieve a string-value interpretation of this XPath
 130  
      *  expression when evaluated against the given context.
 131  
      *
 132  
      *  <p>
 133  
      *  The string-value of the expression is determined per
 134  
      *  the <code>string(..)</code> core function as defined
 135  
      *  in the XPath specification.  This means that an expression
 136  
      *  that selects more than one nodes will return the string value
 137  
      *  of the first node in the node set..
 138  
      *  </p>
 139  
      *
 140  
      *  @param context the node, node-set or Context object for evaluation. 
 141  
      *     This value can be null
 142  
      *
 143  
      *  @return the string-value interpretation of this expression
 144  
      *
 145  
      *  @throws JaxenException if an error occurs while attempting
 146  
      *          to evaluate the expression
 147  
      */
 148  
      String stringValueOf(Object context)
 149  
         throws JaxenException;
 150  
     
 151  
     /** Retrieve the boolean value of the first node in document order
 152  
      *  returned by this XPath expression when evaluated in 
 153  
      *  the given context.
 154  
      *
 155  
      *  <p>
 156  
      *  The boolean-value of the expression is determined per
 157  
      *  the <code>boolean()</code> function defined
 158  
      *  in the XPath specification.  This means that an expression
 159  
      *  that selects zero nodes will return <code>false</code>,
 160  
      *  while an expression that selects one or more nodes will
 161  
      *  return <code>true</code>. An expression that returns a string
 162  
      *  returns false for empty strings and true for all other strings.
 163  
      *  An expression that returns a number
 164  
      *  returns false for zero and true for non-zero numbers.
 165  
      *  </p>
 166  
      *
 167  
      *  @param context the node, node-set or Context object for evaluation. This value can be null.
 168  
      *
 169  
      *  @return the boolean-value of this expression
 170  
      *
 171  
      *  @throws JaxenException if an error occurs while attempting
 172  
      *          to evaluate the expression
 173  
      */
 174  
     boolean booleanValueOf(Object context)
 175  
         throws JaxenException;
 176  
     
 177  
 
 178  
     /** Retrieve the number-value of the first node in document order
 179  
      *  returned by this XPath expression when evaluated in 
 180  
      *  the given context.
 181  
      *
 182  
      *  <p>
 183  
      *  The number-value of the expression is determined per
 184  
      *  the <code>number(..)</code> core function as defined
 185  
      *  in the XPath specification. This means that if this
 186  
      *  expression selects multiple nodes, the number-value
 187  
      *  of the first node is returned.
 188  
      *  </p>
 189  
      *
 190  
      *  @param context the node, node-set or Context object for evaluation. This value can be null.
 191  
      *
 192  
      *  @return the number-value interpretation of this expression
 193  
      *
 194  
      *  @throws JaxenException if an error occurs while attempting
 195  
      *          to evaluate the expression
 196  
      */
 197  
     Number numberValueOf(Object context)
 198  
         throws JaxenException;
 199  
 
 200  
     // ----------------------------------------------------------------------
 201  
     //     Selection
 202  
     // ----------------------------------------------------------------------
 203  
 
 204  
     /** Select all nodes that are selectable by this XPath
 205  
      *  expression. If multiple nodes match, multiple nodes
 206  
      *  will be returned.
 207  
      *
 208  
      *  <p>
 209  
      *  <strong>NOTE:</strong> In most cases, nodes will be returned
 210  
      *  in document-order, as defined by the XML Canonicalization
 211  
      *  specification.  The exception occurs when using XPath
 212  
      *  expressions involving the <code>union</code> operator
 213  
      *  (denoted with the pipe '|' character).
 214  
      *  </p>
 215  
      *
 216  
      *  @see #selectSingleNode
 217  
      *
 218  
      *  @param context the node, node-set or Context object for evaluation. 
 219  
      *     This value can be null.
 220  
      *
 221  
      *  @return the node-set of all items selected
 222  
      *          by this XPath expression.
 223  
      *
 224  
      *  @throws JaxenException if an error occurs while attempting
 225  
      *          to evaluate the expression
 226  
      */
 227  
     List selectNodes(Object context)
 228  
         throws JaxenException;
 229  
 
 230  
     /** 
 231  
      *  <p>
 232  
      *  Return the first node in document order that is selected by this 
 233  
      *  XPath expression.
 234  
      *  </p>
 235  
      *
 236  
      *  @see #selectNodes
 237  
      *
 238  
      *  @param context the node, node-set or Context object for evaluation. 
 239  
      *     This value can be null.
 240  
      *
 241  
      *  @return the first node in document order selected by this XPath expression
 242  
      *
 243  
      *  @throws JaxenException if an error occurs while attempting
 244  
      *          to evaluate the expression
 245  
      */
 246  
     Object selectSingleNode(Object context)
 247  
         throws JaxenException;
 248  
     
 249  
     // ----------------------------------------------------------------------
 250  
     //     Helpers
 251  
     // ----------------------------------------------------------------------
 252  
 
 253  
     /** Add a namespace prefix-to-URI mapping for this XPath
 254  
      *  expression.
 255  
      *
 256  
      *  <p>
 257  
      *  Namespace prefix-to-URI mappings in an XPath are independent
 258  
      *  of those used within any document.  Only the mapping explicitly
 259  
      *  added to this XPath will be available for resolving the
 260  
      *  XPath expression.
 261  
      *  </p>
 262  
      *
 263  
      *  <p>
 264  
      *  This is a convenience method for adding mappings to the
 265  
      *  default {@link NamespaceContext} in place for this XPath.
 266  
      *  If you have installed a specific custom <code>NamespaceContext</code>,
 267  
      *  then this method will throw a <code>JaxenException</code>.
 268  
      *  </p>
 269  
      *
 270  
      *  @param prefix the namespace prefix
 271  
      *  @param uri the namespace URI
 272  
      *
 273  
      *  @throws JaxenException if a <code>NamespaceContext</code>
 274  
      *          used by this XPath has been explicitly installed
 275  
      */
 276  
     void addNamespace(String prefix,
 277  
                       String uri)
 278  
         throws JaxenException;
 279  
 
 280  
     // ----------------------------------------------------------------------
 281  
     //     Properties
 282  
     // ----------------------------------------------------------------------
 283  
     
 284  
     /** Set a <code>NamespaceContext</code> for  this
 285  
      *  XPath expression.
 286  
      *
 287  
      *  <p>
 288  
      *  A <code>NamespaceContext</code> is responsible for translating
 289  
      *  namespace prefixes within the expression into namespace URIs.
 290  
      *  </p>
 291  
      *
 292  
      *  @see NamespaceContext
 293  
      *  @see NamespaceContext#translateNamespacePrefixToUri
 294  
      *
 295  
      *  @param namespaceContext the <code>NamespaceContext</code> to
 296  
      *         install for this expression
 297  
      */
 298  
     void setNamespaceContext(NamespaceContext namespaceContext);
 299  
 
 300  
     /** Set a <code>FunctionContext</code> for  this XPath
 301  
      *  expression.
 302  
      *
 303  
      *  <p>
 304  
      *  A <code>FunctionContext</code> is responsible for resolving
 305  
      *  all function calls used within the expression.
 306  
      *  </p>
 307  
      *
 308  
      *  @see FunctionContext
 309  
      *  @see FunctionContext#getFunction
 310  
      *
 311  
      *  @param functionContext the <code>FunctionContext</code> to
 312  
      *         install for this expression
 313  
      */
 314  
     void setFunctionContext(FunctionContext functionContext);
 315  
 
 316  
     /** Set a <code>VariableContext</code> for this XPath
 317  
      *  expression.
 318  
      *
 319  
      *  <p>
 320  
      *  A <code>VariableContext</code> is responsible for resolving
 321  
      *  all variables referenced within the expression.
 322  
      *  </p>
 323  
      *
 324  
      *  @see VariableContext
 325  
      *  @see VariableContext#getVariableValue
 326  
      *
 327  
      *  @param variableContext the <code>VariableContext</code> to
 328  
      *         install for this expression.
 329  
      */
 330  
     void setVariableContext(VariableContext variableContext);
 331  
 
 332  
     /** Retrieve the <code>NamespaceContext</code> used by this XPath
 333  
      *  expression.
 334  
      *
 335  
      *  <p>
 336  
      *  A <code>FunctionContext</code> is responsible for resolving
 337  
      *  all function calls used within the expression.
 338  
      *  </p>
 339  
      *
 340  
      *  <p>
 341  
      *  If this XPath expression has not previously had a <code>NamespaceContext</code>
 342  
      *  installed, a new default <code>NamespaceContext</code> will be created,
 343  
      *  installed and returned.
 344  
      *  </p>
 345  
      *
 346  
      *  @see NamespaceContext
 347  
      *
 348  
      *  @return the <code>NamespaceContext</code> used by this expression
 349  
      */
 350  
     NamespaceContext getNamespaceContext();
 351  
 
 352  
     /** Retrieve the <code>FunctionContext</code> used by this XPath
 353  
      *  expression.
 354  
      *
 355  
      *  <p>
 356  
      *  A <code>FunctionContext</code> is responsible for resolving
 357  
      *  all function calls used within the expression.
 358  
      *  </p>
 359  
      *
 360  
      *  <p>
 361  
      *  If this XPath expression has not previously had a <code>FunctionContext</code>
 362  
      *  installed, a new default <code>FunctionContext</code> will be created,
 363  
      *  installed and returned.
 364  
      *  </p>
 365  
      *
 366  
      *  @see FunctionContext
 367  
      *
 368  
      *  @return the <code>FunctionContext</code> used by this expression
 369  
      */
 370  
     FunctionContext getFunctionContext();
 371  
 
 372  
     /** Retrieve the <code>VariableContext</code> used by this XPath
 373  
      *  expression.
 374  
      *
 375  
      *  <p>
 376  
      *  A <code>VariableContext</code> is responsible for resolving
 377  
      *  all variables referenced within the expression.
 378  
      *  </p>
 379  
      *
 380  
      *  <p>
 381  
      *  If this XPath expression has not previously had a <code>VariableContext</code>
 382  
      *  installed, a new default <code>VariableContext</code> will be created,
 383  
      *  installed and returned.
 384  
      *  </p>
 385  
      *
 386  
      *  @see VariableContext
 387  
      *  
 388  
      *  @return the <code>VariableContext</code> used by this expression
 389  
      */
 390  
     VariableContext getVariableContext();
 391  
     
 392  
 
 393  
     /** Retrieve the XML object-model-specific {@link Navigator} 
 394  
      *  used to evaluate this XPath expression.
 395  
      *
 396  
      *  @return the implementation-specific <code>Navigator</code>
 397  
      */
 398  
     Navigator getNavigator();
 399  
 }