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