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