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