1 package org.jaxen; 2 3 /* 4 * $Header$ 5 * $Revision$ 6 * $Date$ 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$ 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$ 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 }