001 /* XMLStreamReader.java --
002 Copyright (C) 2005,2006 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.xml.stream;
039
040 import javax.xml.namespace.NamespaceContext;
041 import javax.xml.namespace.QName;
042
043 /**
044 * Interface implemented by an XML parser.
045 */
046 public 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 }