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