View Javadoc

1   package org.jaxen;
2   
3   /*
4    * $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/Navigator.java,v 1.30 2006/06/03 20:07:19 elharo Exp $
5    * $Revision: 1.30 $
6    * $Date: 2006/06/03 20:07:19 $
7    *
8    * ====================================================================
9    *
10   * Copyright 2000-2005 bob mcwhirter & James Strachan.
11   * All rights reserved.
12   *
13   *
14   * Redistribution and use in source and binary forms, with or without
15   * modification, are permitted provided that the following conditions are
16   * met:
17   * 
18   *   * Redistributions of source code must retain the above copyright
19   *     notice, this list of conditions and the following disclaimer.
20   * 
21   *   * Redistributions in binary form must reproduce the above copyright
22   *     notice, this list of conditions and the following disclaimer in the
23   *     documentation and/or other materials provided with the distribution.
24   * 
25   *   * Neither the name of the Jaxen Project nor the names of its
26   *     contributors may be used to endorse or promote products derived 
27   *     from this software without specific prior written permission.
28   * 
29   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
30   * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
31   * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
32   * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
33   * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
34   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
35   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
36   * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
37   * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
38   * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
39   * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40   *
41   * ====================================================================
42   * This software consists of voluntary contributions made by many
43   * individuals on behalf of the Jaxen Project and was originally
44   * created by bob mcwhirter <bob@werken.com> and
45   * James Strachan <jstrachan@apache.org>.  For more information on the
46   * Jaxen Project, please see <http://www.jaxen.org/>.
47   *
48   * $Id: Navigator.java,v 1.30 2006/06/03 20:07:19 elharo Exp $
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      //     Axis Iterators
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     //     Extractors
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     //     isXXX testers
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     //     String-Value extractors
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     //     General utilities
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 }