Java > Open Source Codes > org > jaxen > Navigator


1 package org.jaxen;
2
3 /*
4  * $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/Navigator.java,v 1.25 2005/06/19 13:58:23 elharo Exp $
5  * $Revision: 1.25 $
6  * $Date: 2005/06/19 13:58:23 $
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.25 2005/06/19 13:58:23 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.25 2005/06/19 13:58:23 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 }
563

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags