View Javadoc

1   package org.jaxen;
2   
3   /*
4    * $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/Navigator.java,v 1.23 2005/01/19 01:53:35 bewins Exp $
5    * $Revision: 1.23 $
6    * $Date: 2005/01/19 01:53:35 $
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.23 2005/01/19 01:53:35 bewins Exp $
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      //     Axis Iterators
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     //     Extractors
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     //     isXXX testers
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     //     String-Value extractors
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     //     General utilities
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 }