01: /*
02: * (C) Copyright 2002-2003, Andy Clark. All rights reserved.
03: *
04: * This file is distributed under an Apache style license. Please
05: * refer to the LICENSE file for specific details.
06: */
07:
08: package org.cyberneko.pull;
09:
10: import java.io.IOException;
11:
12: import org.apache.xerces.xni.XNIException;
13:
14: /**
15: * An interface for iterating XML events. Even though this interface
16: * only contains a single method for iterating XML events, higher level
17: * constructs can be written on top of this interface to provide more
18: * powerful iteration capability. However, the <code>nextEvent</code>
19: * method can always be used by applications for complete access to the
20: * event stream.
21: * <p>
22: * Typically, the application will use the iteration method(s) on the
23: * <code>XMLPullParser</code>. But this interface can also be used to
24: * construct any type of event iterator, even one not based on parsing
25: * XML streams.
26: * <p color='red'>
27: * <strong>Note:</strong>
28: * Currently, the <code>XMLEventIterator</code> interface only contains
29: * the single, low-level <code>nextToken</code> method for iterating XML
30: * events. The <code>EventIterator</code> utility class is provided to
31: * handle this shortcoming. As this API progresses, it is believed that
32: * additional methods will be added to the <code>XMLEventIterator</code>
33: * interface. However, this will be decided by actual users of the API.
34: * Please <a href='mailto:andyc@apache.org'>let me know</a> if you have
35: * any suggestions or comments.
36: * </p>
37: *
38: * @author Andy Clark
39: *
40: * @version $Id$
41: */
42: public interface XMLEventIterator {
43:
44: //
45: // XMLEventIterator methods
46: //
47:
48: /**
49: * Returns the next event in the document or null if there are
50: * no more events. This method will return one and only one event
51: * if it is available; it will never return an event chain (i.e.
52: * an event with a non-null <code>next</code> field).
53: *
54: * @exception XNIException Any XNI exception, possibly wrapping
55: * another exception.
56: * @exception IOException An IO exception from the parser, possibly
57: * from a byte stream or character stream
58: * supplied by the parser.
59: */
60: public XMLEvent nextEvent() throws XNIException, IOException;
61:
62: } // interface XMLEventIterator
|