01 package javax.xml.stream;
02
03 import javax.xml.stream.events.XMLEvent;
04 import java.util.Iterator;
05
06 /**
07 *
08 * This is the top level interface for parsing XML Events. It provides
09 * the ability to peek at the next event and returns configuration
10 * information through the property interface.
11 *
12 * @version 1.0
13 * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
14 * @see XMLInputFactory
15 * @see XMLEventWriter
16 * @since 1.6
17 */
18 public interface XMLEventReader extends Iterator {
19 /**
20 * Get the next XMLEvent
21 * @see XMLEvent
22 * @throws XMLStreamException if there is an error with the underlying XML.
23 * @throws NoSuchElementException iteration has no more elements.
24 */
25 public XMLEvent nextEvent() throws XMLStreamException;
26
27 /**
28 * Check if there are more events.
29 * Returns true if there are more events and false otherwise.
30 * @return true if the event reader has more events, false otherwise
31 */
32 public boolean hasNext();
33
34 /**
35 * Check the next XMLEvent without reading it from the stream.
36 * Returns null if the stream is at EOF or has no more XMLEvents.
37 * A call to peek() will be equal to the next return of next().
38 * @see XMLEvent
39 * @throws XMLStreamException
40 */
41 public XMLEvent peek() throws XMLStreamException;
42
43 /**
44 * Reads the content of a text-only element. Precondition:
45 * the current event is START_ELEMENT. Postcondition:
46 * The current event is the corresponding END_ELEMENT.
47 * @throws XMLStreamException if the current event is not a START_ELEMENT
48 * or if a non text element is encountered
49 */
50 public String getElementText() throws XMLStreamException;
51
52 /**
53 * Skips any insignificant space events until a START_ELEMENT or
54 * END_ELEMENT is reached. If anything other than space characters are
55 * encountered, an exception is thrown. This method should
56 * be used when processing element-only content because
57 * the parser is not able to recognize ignorable whitespace if
58 * the DTD is missing or not interpreted.
59 * @throws XMLStreamException if anything other than space characters are encountered
60 */
61 public XMLEvent nextTag() throws XMLStreamException;
62
63 /**
64 * Get the value of a feature/property from the underlying implementation
65 * @param name The name of the property
66 * @return The value of the property
67 * @throws IllegalArgumentException if the property is not supported
68 */
69 public Object getProperty(java.lang.String name)
70 throws java.lang.IllegalArgumentException;
71
72 /**
73 * Frees any resources associated with this Reader. This method does not close the
74 * underlying input source.
75 * @throws XMLStreamException if there are errors freeing associated resources
76 */
77 public void close() throws XMLStreamException;
78 }
|