Coverage Report - org.jaxen.Navigator

Classes in this File Line Coverage Branch Coverage Complexity
Navigator
N/A 
N/A 
1

 1  
 package org.jaxen;
 2  
 
 3  
 /*
 4  
  * $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/Navigator.java,v 1.27 2005/09/23 23:49:20 elharo Exp $
 5  
  * $Revision: 1.27 $
 6  
  * $Date: 2005/09/23 23:49:20 $
 7  
  *
 8  
  * ====================================================================
 9  
  *
 10  
  * Copyright (C) 2000-2005 bob mcwhirter & James Strachan.
 11  
  * All rights reserved.
 12  
  *
 13  
  * Redistribution and use in source and binary forms, with or without
 14  
  * modification, are permitted provided that the following conditions
 15  
  * are met:
 16  
  *
 17  
  * 1. Redistributions of source code must retain the above copyright
 18  
  *    notice, this list of conditions, and the following disclaimer.
 19  
  *
 20  
  * 2. Redistributions in binary form must reproduce the above copyright
 21  
  *    notice, this list of conditions, and the disclaimer that follows
 22  
  *    these conditions in the documentation and/or other materials
 23  
  *    provided with the distribution.
 24  
  *
 25  
  * 3. The name "Jaxen" must not be used to endorse or promote products
 26  
  *    derived from this software without prior written permission.  For
 27  
  *    written permission, please contact license@jaxen.org.
 28  
  *
 29  
  * 4. Products derived from this software may not be called "Jaxen", nor
 30  
  *    may "Jaxen" appear in their name, without prior written permission
 31  
  *    from the Jaxen Project Management (pm@jaxen.org).
 32  
  *
 33  
  * In addition, we request (but do not require) that you include in the
 34  
  * end-user documentation provided with the redistribution and/or in the
 35  
  * software itself an acknowledgement equivalent to the following:
 36  
  *     "This product includes software developed by the
 37  
  *      Jaxen Project <http://www.jaxen.org/>."
 38  
  * Alternatively, the acknowledgment may be graphical using the logos
 39  
  * available at http://www.jaxen.org/
 40  
  *
 41  
  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 42  
  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 43  
  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 44  
  * DISCLAIMED.  IN NO EVENT SHALL THE Jaxen AUTHORS OR THE PROJECT
 45  
  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 46  
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 47  
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 48  
  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 49  
  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 50  
  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 51  
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 52  
  * SUCH DAMAGE.
 53  
  *
 54  
  * ====================================================================
 55  
  * This software consists of voluntary contributions made by many
 56  
  * individuals on behalf of the Jaxen Project and was originally
 57  
  * created by bob mcwhirter <bob@werken.com> and
 58  
  * James Strachan <jstrachan@apache.org>.  For more information on the
 59  
  * Jaxen Project, please see <http://www.jaxen.org/>.
 60  
  *
 61  
  * $Id: Navigator.java,v 1.27 2005/09/23 23:49:20 elharo Exp $
 62  
 */
 63  
 
 64  
 import java.io.Serializable;
 65  
 import java.util.Iterator;
 66  
 
 67  
 import org.jaxen.saxpath.SAXPathException;
 68  
 
 69  
 /** Interface for navigating around an arbitrary object
 70  
  *  model, using XPath semantics.
 71  
  *
 72  
  *  <p>
 73  
  *  There is a method to obtain a <code>java.util.Iterator</code>,
 74  
  *  for each axis specified by XPath.  If the target object model
 75  
  *  does not support the semantics of a particular axis, an
 76  
  *  {@link UnsupportedAxisException} is to be thrown. If there are
 77  
  *  no nodes on that axis, an empty iterator should be returned.
 78  
  *  </p>
 79  
  *
 80  
  *  @author <a href="mailto:bob@eng.werken.com">bob mcwhirter</a>
 81  
  *  @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
 82  
  *
 83  
  *  @version $Id: Navigator.java,v 1.27 2005/09/23 23:49:20 elharo Exp $
 84  
  */
 85  
 public interface Navigator extends Serializable
 86  
 {
 87  
     // ----------------------------------------------------------------------
 88  
     //     Axis Iterators
 89  
     // ----------------------------------------------------------------------
 90  
 
 91  
     /** Retrieve an <code>Iterator</code> matching the <code>child</code>
 92  
      *  XPath axis.
 93  
      *
 94  
      *  @param contextNode the original context node
 95  
      *
 96  
      *  @return an Iterator capable of traversing the axis, not null
 97  
      *
 98  
      *  @throws UnsupportedAxisException if the semantics of the child axis are
 99  
      *          not supported by this object model
 100  
      */
 101  
     Iterator getChildAxisIterator(Object contextNode)
 102  
         throws UnsupportedAxisException;
 103  
 
 104  
     /** Retrieve an <code>Iterator</code> matching the <code>descendant</code>
 105  
      *  XPath axis.
 106  
      *
 107  
      *  @param contextNode the original context node
 108  
      *
 109  
      *  @return an Iterator capable of traversing the axis, not null
 110  
      *
 111  
      *  @throws UnsupportedAxisException if the semantics of the desscendant axis are
 112  
      *          not supported by this object model
 113  
      */
 114  
     Iterator getDescendantAxisIterator(Object contextNode)
 115  
         throws UnsupportedAxisException;
 116  
 
 117  
     /** Retrieve an <code>Iterator</code> matching the <code>parent</code> XPath axis.
 118  
      *
 119  
      *  @param contextNode the original context node
 120  
      *
 121  
      *  @return an Iterator capable of traversing the axis, not null
 122  
      *
 123  
      *  @throws UnsupportedAxisException if the semantics of the parent axis are
 124  
      *          not supported by this object model
 125  
      */
 126  
     Iterator getParentAxisIterator(Object contextNode)
 127  
         throws UnsupportedAxisException;
 128  
 
 129  
     /** Retrieve an <code>Iterator</code> matching the <code>ancestor</code>
 130  
      *  XPath axis.
 131  
      *
 132  
      *  @param contextNode the original context node
 133  
      *
 134  
      *  @return an Iterator capable of traversing the axis, not null
 135  
      *
 136  
      *  @throws UnsupportedAxisException if the semantics of the ancestor axis are
 137  
      *          not supported by this object model
 138  
      */
 139  
     Iterator getAncestorAxisIterator(Object contextNode)
 140  
         throws UnsupportedAxisException;
 141  
 
 142  
     /** Retrieve an <code>Iterator</code> matching the
 143  
      *  <code>following-sibling</code> XPath axis.
 144  
      *
 145  
      *  @param contextNode the original context node
 146  
      *
 147  
      *  @return an Iterator capable of traversing the axis, not null
 148  
      *
 149  
      *  @throws UnsupportedAxisException if the semantics of the following-sibling axis are
 150  
      *          not supported by this object model
 151  
      */
 152  
     Iterator getFollowingSiblingAxisIterator(Object contextNode)
 153  
         throws UnsupportedAxisException;
 154  
 
 155  
     /** Retrieve an <code>Iterator</code> matching the
 156  
      *  <code>preceding-sibling</code> XPath axis.
 157  
      *
 158  
      *  @param contextNode the original context node
 159  
      *
 160  
      *  @return an Iterator capable of traversing the axis, not null
 161  
      *
 162  
      *  @throws UnsupportedAxisException if the semantics of the preceding-sibling axis are
 163  
      *          not supported by this object model
 164  
      */
 165  
     Iterator getPrecedingSiblingAxisIterator(Object contextNode)
 166  
         throws UnsupportedAxisException;
 167  
 
 168  
     /** Retrieve an <code>Iterator</code> matching the <code>following</code>
 169  
      *  XPath axis.
 170  
      *
 171  
      *  @param contextNode the original context node
 172  
      *
 173  
      *  @return an Iterator capable of traversing the axis, not null
 174  
      *
 175  
      *  @throws UnsupportedAxisException if the semantics of the following axis are
 176  
      *          not supported by this object model
 177  
      */
 178  
     Iterator getFollowingAxisIterator(Object contextNode)
 179  
         throws UnsupportedAxisException;
 180  
 
 181  
     /** Retrieve an <code>Iterator</code> matching the <code>preceding</code> XPath axis.
 182  
      *
 183  
      *  @param contextNode the original context node
 184  
      *
 185  
      *  @return an Iterator capable of traversing the axis, not null
 186  
      *
 187  
      *  @throws UnsupportedAxisException if the semantics of the preceding axis are
 188  
      *          not supported by this object model
 189  
      */
 190  
     Iterator getPrecedingAxisIterator(Object contextNode)
 191  
         throws UnsupportedAxisException;
 192  
 
 193  
     /** Retrieve an <code>Iterator</code> matching the <code>attribute</code>
 194  
      *  XPath axis.
 195  
      *
 196  
      *  @param contextNode the original context node
 197  
      *
 198  
      *  @return an Iterator capable of traversing the axis, not null
 199  
      *
 200  
      *  @throws UnsupportedAxisException if the semantics of the attribute axis are
 201  
      *          not supported by this object model
 202  
      */
 203  
     Iterator getAttributeAxisIterator(Object contextNode)
 204  
         throws UnsupportedAxisException;
 205  
 
 206  
     /** Retrieve an <code>Iterator</code> matching the <code>namespace</code>
 207  
      *  XPath axis.
 208  
      *
 209  
      *  @param contextNode the original context node
 210  
      *
 211  
      *  @return an Iterator capable of traversing the axis, not null
 212  
      *
 213  
      *  @throws UnsupportedAxisException if the semantics of the namespace axis are
 214  
      *          not supported by this object model
 215  
      */
 216  
     Iterator getNamespaceAxisIterator(Object contextNode)
 217  
         throws UnsupportedAxisException;
 218  
 
 219  
     /** Retrieve an <code>Iterator</code> matching the <code>self</code> XPath
 220  
      *  axis.
 221  
      *
 222  
      *  @param contextNode the original context node
 223  
      *
 224  
      *  @return an Iterator capable of traversing the axis, not null
 225  
      *
 226  
      *  @throws UnsupportedAxisException if the semantics of the self axis are
 227  
      *          not supported by this object model
 228  
      */
 229  
     Iterator getSelfAxisIterator(Object contextNode)
 230  
         throws UnsupportedAxisException;
 231  
 
 232  
     /** Retrieve an <code>Iterator</code> matching the
 233  
      *  <code>descendant-or-self</code> XPath axis.
 234  
      *
 235  
      *  @param contextNode the original context node
 236  
      *
 237  
      *  @return an Iterator capable of traversing the axis, not null
 238  
      *
 239  
      *  @throws UnsupportedAxisException if the semantics of the descendant-or-self axis are
 240  
      *          not supported by this object model
 241  
      */
 242  
     Iterator getDescendantOrSelfAxisIterator(Object contextNode)
 243  
         throws UnsupportedAxisException;
 244  
 
 245  
     /** Retrieve an <code>Iterator</code> matching the
 246  
      *  <code>ancestor-or-self</code> XPath axis.
 247  
      *
 248  
      *  @param contextNode the original context node
 249  
      *
 250  
      *  @return an Iterator capable of traversing the axis, not null
 251  
      *
 252  
      *  @throws UnsupportedAxisException if the semantics of the ancestor-or-self axis are
 253  
      *          not supported by this object model
 254  
      */
 255  
     Iterator getAncestorOrSelfAxisIterator(Object contextNode)
 256  
         throws UnsupportedAxisException;
 257  
 
 258  
     // ----------------------------------------------------------------------
 259  
     //     Extractors
 260  
     // ----------------------------------------------------------------------
 261  
 
 262  
     /** Loads a document from the given URI
 263  
      *
 264  
      *  @param uri the URI of the document to load
 265  
      *
 266  
      *  @return the document
 267  
      *
 268  
       * @throws FunctionCallException if the document could not be loaded
 269  
      */
 270  
     Object getDocument(String uri)
 271  
         throws FunctionCallException;
 272  
 
 273  
     /** Returns the document node that contains the given context node.
 274  
      *
 275  
      *  @see #isDocument(Object)
 276  
      *
 277  
      *  @param contextNode the context node
 278  
      *
 279  
      *  @return the document of the context node
 280  
      */
 281  
     Object getDocumentNode(Object contextNode);
 282  
     
 283  
     /** Returns the parent of the given context node.
 284  
      *
 285  
      *  <p>
 286  
      *  The parent of any node must either be a document
 287  
      *  node or an element node.
 288  
      *  </p>
 289  
      *
 290  
      *  @see #isDocument
 291  
      *  @see #isElement
 292  
      *
 293  
      *  @param contextNode the context node
 294  
      *
 295  
      *  @return the parent of the context node, or null if this is a document node.
 296  
      *
 297  
      *  @throws UnsupportedAxisException if the parent axis is not
 298  
      *          supported by the model
 299  
      */
 300  
     Object getParentNode(Object contextNode)
 301  
         throws UnsupportedAxisException;
 302  
     
 303  
     /** Retrieve the namespace URI of the given element node.
 304  
      *
 305  
      *  @param element the context element node
 306  
      *
 307  
      *  @return the namespace URI of the element node
 308  
      */
 309  
     String getElementNamespaceUri(Object element);    
 310  
 
 311  
     /** Retrieve the name of the given element node.
 312  
      *
 313  
      *  @param element the context element node
 314  
      *
 315  
      *  @return the name of the element node
 316  
      */
 317  
     String getElementName(Object element);    
 318  
 
 319  
     /** Retrieve the QName of the given element node.
 320  
      *
 321  
      *  @param element the context element node
 322  
      *
 323  
      *  @return the QName of the element node
 324  
      */
 325  
     String getElementQName(Object element);
 326  
 
 327  
     /** Retrieve the namespace URI of the given attribute node.
 328  
      *
 329  
      *  @param attr the context attribute node
 330  
      *
 331  
      *  @return the namespace URI of the attribute node
 332  
      */
 333  
     String getAttributeNamespaceUri(Object attr);    
 334  
 
 335  
     /** Retrieve the name of the given attribute node.
 336  
      *
 337  
      *  @param attr the context attribute node
 338  
      *
 339  
      *  @return the name of the attribute node
 340  
      */
 341  
     String getAttributeName(Object attr);
 342  
 
 343  
     /** Retrieve the QName of the given attribute node.
 344  
      *
 345  
      *  @param attr the context attribute node
 346  
      *
 347  
      *  @return the qualified name of the attribute node
 348  
      */
 349  
     String getAttributeQName(Object attr);
 350  
 
 351  
     /** Retrieve the target of a processing-instruction.
 352  
      *
 353  
      *  @param pi the context processing-instruction node
 354  
      *
 355  
      *  @return the target of the processing-instruction node
 356  
      */
 357  
     String getProcessingInstructionTarget(Object pi);
 358  
 
 359  
     /** Retrieve the data of a processing-instruction.
 360  
      *
 361  
      *  @param pi the context processing-instruction node
 362  
      *
 363  
      *  @return the data of the processing-instruction node
 364  
      */
 365  
     String getProcessingInstructionData(Object pi);
 366  
 
 367  
     // ----------------------------------------------------------------------
 368  
     //     isXXX testers
 369  
     // ----------------------------------------------------------------------
 370  
 
 371  
     /** Returns whether the given object is a document node. A document node
 372  
      *  is the node that is selected by the XPath expression <code>/</code>.
 373  
      *
 374  
      *  @param object the object to test
 375  
      *
 376  
      *  @return <code>true</code> if the object is a document node,
 377  
      *          else <code>false</code>
 378  
      */
 379  
     boolean isDocument(Object object);
 380  
 
 381  
     /** Returns whether the given object is an element node.
 382  
      *
 383  
      *  @param object the object to test
 384  
      *
 385  
      *  @return <code>true</code> if the object is an element node,
 386  
      *          else <code>false</code>
 387  
      */
 388  
     boolean isElement(Object object);
 389  
 
 390  
     /** Returns whether the given object is an attribute node. 
 391  
      *
 392  
      *  @param object the object to test
 393  
      *
 394  
      *  @return <code>true</code> if the object is an attribute node,
 395  
      *          else <code>false</code>
 396  
      */
 397  
     boolean isAttribute(Object object);
 398  
 
 399  
     /** Returns whether the given object is a namespace node. 
 400  
      *
 401  
      *  @param object the object to test
 402  
      *
 403  
      *  @return <code>true</code> if the object is a namespace node,
 404  
      *          else <code>false</code>
 405  
      */
 406  
     boolean isNamespace(Object object);
 407  
 
 408  
     /** Returns whether the given object is a comment node. 
 409  
      *
 410  
      *  @param object the object to test
 411  
      *
 412  
      *  @return <code>true</code> if the object is a comment node,
 413  
      *          else <code>false</code>
 414  
      */
 415  
     boolean isComment(Object object);
 416  
 
 417  
     /** Returns whether the given object is a text node. 
 418  
      *
 419  
      *  @param object the object to test
 420  
      *
 421  
      *  @return <code>true</code> if the object is a text node,
 422  
      *          else <code>false</code>
 423  
      */
 424  
     boolean isText(Object object);
 425  
 
 426  
     /** Returns whether the given object is a processing-instruction node.
 427  
      *
 428  
      *  @param object the object to test
 429  
      *
 430  
      *  @return <code>true</code> if the object is a processing-instruction node,
 431  
      *          else <code>false</code>
 432  
      */
 433  
     boolean isProcessingInstruction(Object object);
 434  
 
 435  
     // ----------------------------------------------------------------------
 436  
     //     String-Value extractors
 437  
     // ----------------------------------------------------------------------
 438  
 
 439  
     /** Retrieve the string-value of a comment node.
 440  
      * This may be the empty string if the comment is empty,
 441  
      * but must not be null.
 442  
      *
 443  
      *  @param comment the comment node
 444  
      *
 445  
      *  @return the string-value of the node
 446  
      */
 447  
     String getCommentStringValue(Object comment);
 448  
 
 449  
     /** Retrieve the string-value of an element node.
 450  
      * This may be the empty string if the element is empty,
 451  
      * but must not be null.
 452  
      *
 453  
      *  @param element the comment node.
 454  
      *
 455  
      *  @return the string-value of the node.
 456  
      */
 457  
     String getElementStringValue(Object element);
 458  
 
 459  
     /** Retrieve the string-value of an attribute node. 
 460  
      *  This should be the XML 1.0 normalized attribute value.
 461  
      *  This may be the empty string but must not be null. 
 462  
      *
 463  
      *  @param attr the attribute node
 464  
      *
 465  
      *  @return the string-value of the node
 466  
      */
 467  
     String getAttributeStringValue(Object attr);
 468  
 
 469  
     /** Retrieve the string-value of a namespace node.
 470  
      * This is generally the namespace URI.
 471  
      * This may be the empty string but must not be null.
 472  
      *
 473  
      *  @param ns the namespace node
 474  
      *
 475  
      *  @return the string-value of the node
 476  
      */
 477  
     String getNamespaceStringValue(Object ns);
 478  
 
 479  
     /** Retrieve the string-value of a text node.
 480  
      * This must not be null and should not be the empty string.
 481  
      * The XPath data model does not allow empty text nodes.
 482  
      *
 483  
      *  @param text the text node
 484  
      *
 485  
      *  @return the string-value of the node
 486  
      */
 487  
     String getTextStringValue(Object text);
 488  
 
 489  
     // ----------------------------------------------------------------------
 490  
     //     General utilities
 491  
     // ----------------------------------------------------------------------
 492  
 
 493  
     /** Retrieve the namespace prefix of a namespace node.
 494  
      *
 495  
      *  @param ns the namespace node
 496  
      *
 497  
      *  @return the prefix associated with the node
 498  
      */
 499  
     String getNamespacePrefix(Object ns);
 500  
 
 501  
     
 502  
     /** Translate a namespace prefix to a namespace URI, <b>possibly</b>
 503  
      *  considering a particular element node.
 504  
      *
 505  
      *  <p>
 506  
      *  Strictly speaking, prefix-to-URI translation should occur
 507  
      *  irrespective of any element in the document.  This method
 508  
      *  is provided to allow a non-conforming ease-of-use enhancement.
 509  
      *  </p>
 510  
      *
 511  
      *  @see NamespaceContext
 512  
      *
 513  
      *  @param prefix the prefix to translate
 514  
      *  @param element the element to consider during translation
 515  
      *
 516  
      *  @return the namespace URI associated with the prefix
 517  
      */
 518  
     String translateNamespacePrefixToUri(String prefix,
 519  
                                          Object element);
 520  
 
 521  
     /** Returns a parsed form of the given XPath string, which will be suitable
 522  
      *  for queries on documents that use the same navigator as this one.
 523  
      *
 524  
      *  @see XPath
 525  
      *
 526  
      *  @param xpath the XPath expression
 527  
      *
 528  
      *  @return a new XPath expression object
 529  
      *
 530  
      *  @throws SAXPathException if the string is not a syntactically 
 531  
      *      correct XPath expression
 532  
      */
 533  
     XPath parseXPath(String xpath) throws SAXPathException;
 534  
 
 535  
     /**
 536  
      *  Returns the element whose ID is given by elementId.
 537  
      *  If no such element exists, returns null.
 538  
      *  Attributes with the name "ID" are not of type ID unless so defined.
 539  
      *  Implementations that do not know whether attributes are of type ID or
 540  
      *  not are expected to return null.
 541  
      *
 542  
      *  @param contextNode   a node from the document in which to look for the
 543  
      *                       id
 544  
      *  @param elementId   id to look for
 545  
      *
 546  
      *  @return   element whose ID is given by elementId, or null if no such
 547  
      *            element exists in the document or if the implementation
 548  
      *            does not know about attribute types
 549  
      */
 550  
     Object getElementById(Object contextNode,
 551  
                           String elementId);
 552  
 
 553  
     /** Returns a number that identifies the type of node that the given
 554  
      *  object represents in this navigator.
 555  
      * 
 556  
      * @param node ????
 557  
      * @return ????
 558  
      *
 559  
      *  @see org.jaxen.pattern.Pattern
 560  
      */
 561  
     short getNodeType(Object node);
 562  
 }