Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Navigator |
|
| 1.0;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 | } |