Coverage Report - org.jaxen.Navigator

Classes in this Package	Line Coverage	Branch Coverage	Complexity
Navigator	N/A	N/A	1.0;1

1		package org.jaxen;
2
3		/*
4		* $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/Navigator.java,v 1.24 2005/04/29 02:43:45 elharo Exp $
5		* $Revision: 1.24 $
6		* $Date: 2005/04/29 02:43:45 $
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.24 2005/04/29 02:43:45 elharo 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.24 2005/04/29 02:43:45 elharo 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 the child 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 the desscendant 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 the parent 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 the ancestor 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 the following-sibling 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 the preceding-sibling 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 the following 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 the preceding 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 the attribute 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 the namespace 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 the self 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 the descendant-or-self 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 the ancestor-or-self 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 qualified name 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		* @param node ????
546		* @return ????
547		*
548		* @see org.jaxen.pattern.Pattern
549		*/
550		short getNodeType(Object node);
551		}