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}
301