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