1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 27 */ 28 29 package javax.xml.stream; 30 31 import javax.xml.stream.events.XMLEvent; 32 33 import java.util.Iterator; 34 35 /** 36 * 37 * This is the top level interface for parsing XML Events. It provides 38 * the ability to peek at the next event and returns configuration 39 * information through the property interface. 40 * 41 * @version 1.0 42 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 43 * @see XMLInputFactory 44 * @see XMLEventWriter 45 * @since 1.6 46 */ 47 public interface XMLEventReader extends Iterator { 48 /** 49 * Get the next XMLEvent 50 * @see XMLEvent 51 * @throws XMLStreamException if there is an error with the underlying XML. 52 * @throws NoSuchElementException iteration has no more elements. 53 */ nextEvent()54 public XMLEvent nextEvent() throws XMLStreamException; 55 56 /** 57 * Check if there are more events. 58 * Returns true if there are more events and false otherwise. 59 * @return true if the event reader has more events, false otherwise 60 */ hasNext()61 public boolean hasNext(); 62 63 /** 64 * Check the next XMLEvent without reading it from the stream. 65 * Returns null if the stream is at EOF or has no more XMLEvents. 66 * A call to peek() will be equal to the next return of next(). 67 * @see XMLEvent 68 * @throws XMLStreamException 69 */ peek()70 public XMLEvent peek() throws XMLStreamException; 71 72 /** 73 * Reads the content of a text-only element. Precondition: 74 * the current event is START_ELEMENT. Postcondition: 75 * The current event is the corresponding END_ELEMENT. 76 * @throws XMLStreamException if the current event is not a START_ELEMENT 77 * or if a non text element is encountered 78 */ getElementText()79 public String getElementText() throws XMLStreamException; 80 81 /** 82 * Skips any insignificant space events until a START_ELEMENT or 83 * END_ELEMENT is reached. If anything other than space characters are 84 * encountered, an exception is thrown. This method should 85 * be used when processing element-only content because 86 * the parser is not able to recognize ignorable whitespace if 87 * the DTD is missing or not interpreted. 88 * @throws XMLStreamException if anything other than space characters are encountered 89 */ nextTag()90 public XMLEvent nextTag() throws XMLStreamException; 91 92 /** 93 * Get the value of a feature/property from the underlying implementation 94 * @param name The name of the property 95 * @return The value of the property 96 * @throws IllegalArgumentException if the property is not supported 97 */ getProperty(java.lang.String name)98 public Object getProperty(java.lang.String name) throws java.lang.IllegalArgumentException; 99 100 /** 101 * Frees any resources associated with this Reader. This method does not close the 102 * underlying input source. 103 * @throws XMLStreamException if there are errors freeing associated resources 104 */ close()105 public void close() throws XMLStreamException; 106 } 107