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.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 | } |