001/* XMLStreamReader.java -- 002 Copyright (C) 2005,2006 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038package javax.xml.stream; 039 040import javax.xml.namespace.NamespaceContext; 041import javax.xml.namespace.QName; 042 043/** 044 * Interface implemented by an XML parser. 045 */ 046public interface XMLStreamReader 047 extends XMLStreamConstants 048{ 049 050 /** 051 * Returns the implementation-specific feature or property of the given 052 * name. 053 */ 054 Object getProperty(String name) 055 throws IllegalArgumentException; 056 057 /** 058 * Returns the next parsing event. 059 */ 060 int next() 061 throws XMLStreamException; 062 063 /** 064 * Tests whether the current event is of the given type and namespace. 065 * @exception XMLStreamException if the test fails 066 */ 067 void require(int type, String namespaceURI, String localName) 068 throws XMLStreamException; 069 070 /** 071 * Returns the text content of a text-only element. 072 * When invoked, the current event must be START_ELEMENT. 073 * On completion, the current event will be END_ELEMENT. 074 */ 075 String getElementText() 076 throws XMLStreamException; 077 078 /** 079 * Skips any ignorable whitespace, comments, and processing instructions 080 * until a START_ELEMENT or END_ELEMENT event is encountered. 081 * @exception XMLStreamException if an event of any other type is 082 * encountered 083 */ 084 int nextTag() 085 throws XMLStreamException; 086 087 /** 088 * Indicates whether there are any remaining events to be read. 089 */ 090 boolean hasNext() 091 throws XMLStreamException; 092 093 /** 094 * Frees any resources used by this parser. 095 * This method will not close the underlying input source. 096 */ 097 void close() 098 throws XMLStreamException; 099 100 /** 101 * Returns the namespace URI for the given prefix. 102 */ 103 String getNamespaceURI(String prefix); 104 105 /** 106 * Indicates whether the current event is START_ELEMENT. 107 */ 108 boolean isStartElement(); 109 110 /** 111 * Indicates whether the current event is END_ELEMENT. 112 */ 113 boolean isEndElement(); 114 115 /** 116 * Indicates whether the current event is character data. 117 */ 118 boolean isCharacters(); 119 120 /** 121 * Indicates whether the current event is ignorable whitespace. 122 */ 123 boolean isWhiteSpace(); 124 125 /** 126 * Returns the normalized attribute value for the given attribute. 127 */ 128 String getAttributeValue(String namespaceURI, String localName); 129 130 /** 131 * Returns the number of attributes on this element. 132 * This method can only be invoked on a START_ELEMENT event. 133 */ 134 int getAttributeCount(); 135 136 /** 137 * Returns the QName of the attribute at the given index. 138 */ 139 QName getAttributeName(int index); 140 141 /** 142 * Returns the namespace URI of the attribute at the given index. 143 */ 144 String getAttributeNamespace(int index); 145 146 /** 147 * Returns the local-name of the attribute at the given index. 148 */ 149 String getAttributeLocalName(int index); 150 151 /** 152 * Returns the namespace prefix of the attribute at the given index. 153 */ 154 String getAttributePrefix(int index); 155 156 /** 157 * Returns the type of the attribute at the specified index. 158 */ 159 String getAttributeType(int index); 160 161 /** 162 * Returns the normalized value of the attribute at the given index. 163 */ 164 String getAttributeValue(int index); 165 166 /** 167 * Indicates whether the attribute at the given index was specified in the 168 * underlying XML source or created by default. 169 */ 170 boolean isAttributeSpecified(int index); 171 172 /** 173 * Returns the number of namespaces declared on this event. 174 * This method is only valid on a START_ELEMENT, END_ELEMENT, or NAMESPACE 175 * event. 176 */ 177 int getNamespaceCount(); 178 179 /** 180 * Returns the prefix of the namespace at the given index, or null if this 181 * is the default namespace declaration. 182 */ 183 String getNamespacePrefix(int index); 184 185 /** 186 * Returns the URI of the namespace at the given index. 187 */ 188 String getNamespaceURI(int index); 189 190 /** 191 * Returns the namespace context for the current position. 192 */ 193 NamespaceContext getNamespaceContext(); 194 195 /** 196 * Returns the type of the current event. 197 */ 198 int getEventType(); 199 200 /** 201 * Returns the string value of the current event. 202 */ 203 String getText(); 204 205 /** 206 * Returns the string value of the current event as a character array. 207 */ 208 char[] getTextCharacters(); 209 210 /** 211 * Copies the string value of the current event into the specified 212 * character array. 213 */ 214 int getTextCharacters(int sourceStart, char[] target, 215 int targetStart, int length) 216 throws XMLStreamException; 217 218 /** 219 * Returns the offset of the first character in the text character array. 220 */ 221 int getTextStart(); 222 223 /** 224 * Returns the length of the characters in the text character array. 225 */ 226 int getTextLength(); 227 228 /** 229 * Returns the input encoding. 230 */ 231 String getEncoding(); 232 233 /** 234 * Indicates whether the current event has text. 235 */ 236 boolean hasText(); 237 238 /** 239 * Returns the current location of the parser cursor in the underlying 240 * input source. 241 */ 242 Location getLocation(); 243 244 /** 245 * Returns the QName of the current element. 246 * This method is only valid on a START_ELEMENT or END_ELEMENT event. 247 */ 248 QName getName(); 249 250 /** 251 * Returns the local-name of the current element. 252 */ 253 String getLocalName(); 254 255 /** 256 * Indicates whether the current event has a name. 257 */ 258 boolean hasName(); 259 260 /** 261 * Returns the namespace URI of the current element. 262 */ 263 String getNamespaceURI(); 264 265 /** 266 * Returns the namespace prefix of the current element. 267 */ 268 String getPrefix(); 269 270 /** 271 * Returns the XML version declared in the XML declaration. 272 */ 273 String getVersion(); 274 275 /** 276 * Returns the standalone flag declared in the XML declaration. 277 */ 278 boolean isStandalone(); 279 280 /** 281 * Indicates whether the standalone flag was set in the document. 282 */ 283 boolean standaloneSet(); 284 285 /** 286 * Returns the encoding declared in the XML declaration. 287 */ 288 String getCharacterEncodingScheme(); 289 290 /** 291 * Returns the target of the current processing instruction event. 292 */ 293 String getPITarget(); 294 295 /** 296 * Returns the data of the current processing instruction event. 297 */ 298 String getPIData(); 299 300}