1 package org.jaxen;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64 import java.io.Serializable;
65 import java.util.Iterator;
66
67 /*** Interface for navigating around an arbitrary object
68 * model, using XPath semantics.
69 *
70 * <p>
71 * There is a method to obtain a <code>java.util.Iterator</code>,
72 * for each axis specified by XPath. If the target object model
73 * does not support the semantics of a particular axis, an
74 * {@link UnsupportedAxisException} is to be thrown. If there are
75 * no nodes on that axis, an empty iterator should be returned.
76 * </p>
77 *
78 * @author <a href="mailto:bob@eng.werken.com">bob mcwhirter</a>
79 * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
80 *
81 * @version $Id: Navigator.java,v 1.23 2005/01/19 01:53:35 bewins Exp $
82 */
83 public interface Navigator extends Serializable
84 {
85
86
87
88
89 /*** Retrieve an <code>Iterator</code> matching the <code>child</code>
90 * XPath axis.
91 *
92 * @param contextNode the original context node
93 *
94 * @return An Iterator capable of traversing the axis, not null.
95 *
96 * @throws UnsupportedAxisException if the semantics of this axis are
97 * not supported by this object model
98 */
99 Iterator getChildAxisIterator(Object contextNode)
100 throws UnsupportedAxisException;
101
102 /*** Retrieve an <code>Iterator</code> matching the <code>descendant</code>
103 * XPath axis.
104 *
105 * @param contextNode the original context node
106 *
107 * @return An Iterator capable of traversing the axis, not null.
108 *
109 * @throws UnsupportedAxisException if the semantics of this axis are
110 * not supported by this object model
111 */
112 Iterator getDescendantAxisIterator(Object contextNode)
113 throws UnsupportedAxisException;
114
115 /*** Retrieve an <code>Iterator</code> matching the <code>parent</code> XPath axis.
116 *
117 * @param contextNode the original context node
118 *
119 * @return An Iterator capable of traversing the axis, not null.
120 *
121 * @throws UnsupportedAxisException if the semantics of this axis are
122 * not supported by this object model
123 */
124 Iterator getParentAxisIterator(Object contextNode)
125 throws UnsupportedAxisException;
126
127 /*** Retrieve an <code>Iterator</code> matching the <code>ancestor</code>
128 * XPath axis.
129 *
130 * @param contextNode the original context node
131 *
132 * @return An Iterator capable of traversing the axis, not null.
133 *
134 * @throws UnsupportedAxisException if the semantics of this axis are
135 * not supported by this object model
136 */
137 Iterator getAncestorAxisIterator(Object contextNode)
138 throws UnsupportedAxisException;
139
140 /*** Retrieve an <code>Iterator</code> matching the
141 * <code>following-sibling</code> XPath axis.
142 *
143 * @param contextNode the original context node
144 *
145 * @return An Iterator capable of traversing the axis, not null.
146 *
147 * @throws UnsupportedAxisException if the semantics of this axis are
148 * not supported by this object model
149 */
150 Iterator getFollowingSiblingAxisIterator(Object contextNode)
151 throws UnsupportedAxisException;
152
153 /*** Retrieve an <code>Iterator</code> matching the
154 * <code>preceding-sibling</code> XPath axis.
155 *
156 * @param contextNode the original context node
157 *
158 * @return An Iterator capable of traversing the axis, not null.
159 *
160 * @throws UnsupportedAxisException if the semantics of this axis are
161 * not supported by this object model
162 */
163 Iterator getPrecedingSiblingAxisIterator(Object contextNode)
164 throws UnsupportedAxisException;
165
166 /*** Retrieve an <code>Iterator</code> matching the <code>following</code>
167 * XPath axis.
168 *
169 * @param contextNode the original context node
170 *
171 * @return An Iterator capable of traversing the axis, not null.
172 *
173 * @throws UnsupportedAxisException if the semantics of this axis are
174 * not supported by this object model
175 */
176 Iterator getFollowingAxisIterator(Object contextNode)
177 throws UnsupportedAxisException;
178
179 /*** Retrieve an <code>Iterator</code> matching the <code>preceding</code> XPath axis.
180 *
181 * @param contextNode the original context node
182 *
183 * @return An Iterator capable of traversing the axis, not null.
184 *
185 * @throws UnsupportedAxisException if the semantics of this axis are
186 * not supported by this object model
187 */
188 Iterator getPrecedingAxisIterator(Object contextNode)
189 throws UnsupportedAxisException;
190
191 /*** Retrieve an <code>Iterator</code> matching the <code>attribute</code>
192 * XPath axis.
193 *
194 * @param contextNode the original context node
195 *
196 * @return An Iterator capable of traversing the axis, not null.
197 *
198 * @throws UnsupportedAxisException if the semantics of this axis are
199 * not supported by this object model
200 */
201 Iterator getAttributeAxisIterator(Object contextNode)
202 throws UnsupportedAxisException;
203
204 /*** Retrieve an <code>Iterator</code> matching the <code>namespace</code>
205 * XPath axis.
206 *
207 * @param contextNode the original context node
208 *
209 * @return An Iterator capable of traversing the axis, not null.
210 *
211 * @throws UnsupportedAxisException if the semantics of this axis are
212 * not supported by this object model
213 */
214 Iterator getNamespaceAxisIterator(Object contextNode)
215 throws UnsupportedAxisException;
216
217 /*** Retrieve an <code>Iterator</code> matching the <code>self</code> xpath
218 * axis.
219 *
220 * @param contextNode the original context node
221 *
222 * @return An Iterator capable of traversing the axis, not null.
223 *
224 * @throws UnsupportedAxisException if the semantics of this axis are
225 * not supported by this object model
226 */
227 Iterator getSelfAxisIterator(Object contextNode)
228 throws UnsupportedAxisException;
229
230 /*** Retrieve an <code>Iterator</code> matching the
231 * <code>descendant-or-self</code> XPath axis.
232 *
233 * @param contextNode the original context node
234 *
235 * @return An Iterator capable of traversing the axis, not null.
236 *
237 * @throws UnsupportedAxisException if the semantics of this axis are
238 * not supported by this object model
239 */
240 Iterator getDescendantOrSelfAxisIterator(Object contextNode)
241 throws UnsupportedAxisException;
242
243 /*** Retrieve an <code>Iterator</code> matching the
244 * <code>ancestor-or-self</code> XPath axis.
245 *
246 * @param contextNode the original context node
247 *
248 * @return An Iterator capable of traversing the axis, not null.
249 *
250 * @throws UnsupportedAxisException if the semantics of this axis are
251 * not supported by this object model
252 */
253 Iterator getAncestorOrSelfAxisIterator(Object contextNode)
254 throws UnsupportedAxisException;
255
256
257
258
259
260 /*** Loads a document from the given URI
261 *
262 * @param uri the URI of the document to load
263 *
264 * @return the document
265 *
266 * @throws FunctionCallException if the document could not be loaded
267 */
268 Object getDocument(String uri)
269 throws FunctionCallException;
270
271 /*** Returns the document node that contains the given context node.
272 *
273 * @see #isDocument(Object)
274 *
275 * @param contextNode the context node
276 *
277 * @return the document of the context node
278 */
279 Object getDocumentNode(Object contextNode);
280
281 /*** Returns the parent of the given context node.
282 *
283 * <p>
284 * The parent of any node must either be a document
285 * node or an element node.
286 * </p>
287 *
288 * @see #isDocument
289 * @see #isElement
290 *
291 * @param contextNode the context node
292 *
293 * @return The parent of the context node, or null if this is a document node.
294 *
295 * @throws UnsupportedAxisException If the parent axis is not
296 * supported by the model.
297 */
298 Object getParentNode(Object contextNode)
299 throws UnsupportedAxisException;
300
301 /*** Retrieve the namespace URI of the given element node.
302 *
303 * @param element the context element node
304 *
305 * @return the namespace URI of the element node
306 */
307 String getElementNamespaceUri(Object element);
308
309 /*** Retrieve the name of the given element node.
310 *
311 * @param element the context element node
312 *
313 * @return the name of the element node
314 */
315 String getElementName(Object element);
316
317 /*** Retrieve the QName of the given element node.
318 *
319 * @param element the context element node
320 *
321 * @return the QName of the element node
322 */
323 String getElementQName(Object element);
324
325 /*** Retrieve the namespace URI of the given attribute node.
326 *
327 * @param attr The context attribute node
328 *
329 * @return the namespace URI of the attribute node
330 */
331 String getAttributeNamespaceUri(Object attr);
332
333 /*** Retrieve the name of the given attribute node.
334 *
335 * @param attr The context attribute node
336 *
337 * @return the name of the attribute node
338 */
339 String getAttributeName(Object attr);
340
341 /*** Retrieve the QName of the given attribute node.
342 *
343 * @param attr The context attribute node.
344 *
345 * @return the QName of the attribute node.
346 */
347 String getAttributeQName(Object attr);
348
349 /*** Retrieve the target of a processing-instruction.
350 *
351 * @param pi The context processing-instruction node.
352 *
353 * @return the target of the processing-instruction node.
354 */
355 String getProcessingInstructionTarget(Object pi);
356
357 /*** Retrieve the data of a processing-instruction.
358 *
359 * @param pi The context processing-instruction node.
360 *
361 * @return the data of the processing-instruction node.
362 */
363 String getProcessingInstructionData(Object pi);
364
365
366
367
368
369 /*** Returns whether the given object is a document node. A document node
370 * is the node that is selected by the xpath expression <code>/</code>.
371 *
372 * @param object the object to test.
373 *
374 * @return <code>true</code> if the object is a document node,
375 * else <code>false</code>
376 */
377 boolean isDocument(Object object);
378
379 /*** Returns whether the given object is an element node.
380 *
381 * @param object the object to test.
382 *
383 * @return <code>true</code> if the object is an element node,
384 * else <code>false</code>
385 */
386 boolean isElement(Object object);
387
388 /*** Returns whether the given object is an attribute node.
389 *
390 * @param object the object to test.
391 *
392 * @return <code>true</code> if the object is an attribute node,
393 * else <code>false</code>
394 */
395 boolean isAttribute(Object object);
396
397 /*** Returns whether the given object is a namespace node.
398 *
399 * @param object the object to test.
400 *
401 * @return <code>true</code> if the object is a namespace node,
402 * else <code>false</code>
403 */
404 boolean isNamespace(Object object);
405
406 /*** Returns whether the given object is a comment node.
407 *
408 * @param object the object to test.
409 *
410 * @return <code>true</code> if the object is a comment node,
411 * else <code>false</code>
412 */
413 boolean isComment(Object object);
414
415 /*** Returns whether the given object is a text node.
416 *
417 * @param object the object to test.
418 *
419 * @return <code>true</code> if the object is a text node,
420 * else <code>false</code>
421 */
422 boolean isText(Object object);
423
424 /*** Returns whether the given object is a processing-instruction node.
425 *
426 * @param object the object to test.
427 *
428 * @return <code>true</code> if the object is a processing-instruction node,
429 * else <code>false</code>
430 */
431 boolean isProcessingInstruction(Object object);
432
433
434
435
436
437 /*** Retrieve the string-value of a comment node.
438 *
439 * @param comment the comment node
440 *
441 * @return the string-value of the node
442 */
443 String getCommentStringValue(Object comment);
444
445 /*** Retrieve the string-value of an element node.
446 *
447 * @param element The comment node.
448 *
449 * @return The string-value of the node.
450 */
451 String getElementStringValue(Object element);
452
453 /*** Retrieve the string-value of an attribute node.
454 *
455 * @param attr the attribute node
456 *
457 * @return the string-value of the node
458 */
459 String getAttributeStringValue(Object attr);
460
461 /*** Retrieve the string-value of a namespace node.
462 *
463 * @param ns The namespace node
464 *
465 * @return the string-value of the node
466 */
467 String getNamespaceStringValue(Object ns);
468
469 /*** Retrieve the string-value of a text node.
470 *
471 * @param txt the text node
472 *
473 * @return the string-value of the node
474 */
475 String getTextStringValue(Object txt);
476
477
478
479
480
481 /*** Retrieve the namespace prefix of a namespace node.
482 *
483 * @param ns the namespace node
484 *
485 * @return the prefix associated with the node
486 */
487 String getNamespacePrefix(Object ns);
488
489
490 /*** Translate a namespace prefix to a namespace URI, <b>possibly</b>
491 * considering a particular element node.
492 *
493 * <p>
494 * Strictly speaking, prefix-to-URI translation should occur
495 * irrespective of any element in the document. This method
496 * is provided to allow a non-conforming ease-of-use enhancement.
497 * </p>
498 *
499 * @see NamespaceContext
500 *
501 * @param prefix the prefix to translate
502 * @param element the element to consider during translation
503 *
504 * @return the namespace URI associated with the prefix
505 */
506 String translateNamespacePrefixToUri(String prefix,
507 Object element);
508
509 /*** Returns a parsed form of the given xpath string, which will be suitable
510 * for queries on documents that use the same navigator as this one.
511 *
512 * @see XPath
513 *
514 * @param xpath the XPath expression
515 *
516 * @return a new XPath expression object
517 *
518 * @throws org.jaxen.saxpath.SAXPathException if an error occurs while parsing the
519 * XPath expression
520 */
521 XPath parseXPath(String xpath)
522 throws org.jaxen.saxpath.SAXPathException;
523
524 /***
525 * Returns the element whose ID is given by elementId.
526 * If no such element exists, returns null.
527 * Attributes with the name "ID" are not of type ID unless so defined.
528 * Implementations that do not know whether attributes are of type ID or
529 * not are expected to return null.
530 *
531 * @param contextNode a node from the document in which to look for the
532 * id
533 * @param elementId id to look for
534 *
535 * @return element whose ID is given by elementId, or null if no such
536 * element exists in the document or if the implementation
537 * does not know about attribute types
538 */
539 Object getElementById(Object contextNode,
540 String elementId);
541
542 /*** Returns a number that identifies the type of node that the given
543 * object represents in this navigator.
544 *
545 * @see org.jaxen.pattern.Pattern
546 */
547 short getNodeType(Object node);
548 }