View Javadoc

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 }