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 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.25 2005/06/19 13:58:23 elharo Exp $
84 */
85 public interface Navigator extends Serializable
86 {
87
88
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
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
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
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
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 }