View Javadoc
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 java.io.Reader;
32  import javax.xml.namespace.NamespaceContext;
33  import javax.xml.namespace.QName;
34  
35  /**
36   *  The XMLStreamReader interface allows forward, read-only access to XML.
37   *  It is designed to be the lowest level and most efficient way to
38   *  read XML data.
39   *
40   * <p> The XMLStreamReader is designed to iterate over XML using
41   * next() and hasNext().  The data can be accessed using methods such as getEventType(),
42   * getNamespaceURI(), getLocalName() and getText();
43   *
44   * <p> The <a href="#next()">next()</a> method causes the reader to read the next parse event.
45   * The next() method returns an integer which identifies the type of event just read.
46   * <p> The event type can be determined using <a href="#getEventType()">getEventType()</a>.
47   * <p> Parsing events are defined as the XML Declaration, a DTD,
48   * start tag, character data, white space, end tag, comment,
49   * or processing instruction.  An attribute or namespace event may be encountered
50   * at the root level of a document as the result of a query operation.
51   *
52   * <p>For XML 1.0 compliance an XML processor must pass the
53   * identifiers of declared unparsed entities, notation declarations and their
54   * associated identifiers to the application.  This information is
55   * provided through the property API on this interface.
56   * The following two properties allow access to this information:
57   * javax.xml.stream.notations and javax.xml.stream.entities.
58   * When the current event is a DTD the following call will return a
59   * list of Notations
60   *  <code>List l = (List) getProperty("javax.xml.stream.notations");</code>
61   * The following call will return a list of entity declarations:
62   * <code>List l = (List) getProperty("javax.xml.stream.entities");</code>
63   * These properties can only be accessed during a DTD event and
64   * are defined to return null if the information is not available.
65   *
66   * <p>The following table describes which methods are valid in what state.
67   * If a method is called in an invalid state the method will throw a
68   * java.lang.IllegalStateException.
69   *
70   * <table border="2" rules="all" cellpadding="4">
71   *   <thead>
72   *     <tr>
73   *       <th align="center" colspan="2">
74   *         Valid methods for each state
75   *       </th>
76   *     </tr>
77   *   </thead>
78   *   <tbody>
79   *     <tr>
80   *       <th>Event Type</th>
81   *       <th>Valid Methods</th>
82   *     </tr>
83   *     <tr>
84   *       <td> All States  </td>
85   *       <td> getProperty(), hasNext(), require(), close(),
86   *            getNamespaceURI(), isStartElement(),
87   *            isEndElement(), isCharacters(), isWhiteSpace(),
88   *            getNamespaceContext(), getEventType(),getLocation(),
89   *            hasText(), hasName()
90   *       </td>
91   *     </tr>
92   *     <tr>
93   *       <td> START_ELEMENT  </td>
94   *       <td> next(), getName(), getLocalName(), hasName(), getPrefix(),
95   *            getAttributeXXX(), isAttributeSpecified(),
96   *            getNamespaceXXX(),
97   *            getElementText(), nextTag()
98   *       </td>
99   *     </tr>
100  *       <td> ATTRIBUTE  </td>
101  *       <td> next(), nextTag()
102  *            getAttributeXXX(), isAttributeSpecified(),
103  *       </td>
104  *     </tr>
105  *     </tr>
106  *       <td> NAMESPACE  </td>
107  *       <td> next(), nextTag()
108  *            getNamespaceXXX()
109  *       </td>
110  *     </tr>
111  *     <tr>
112  *       <td> END_ELEMENT  </td>
113  *       <td> next(), getName(), getLocalName(), hasName(), getPrefix(),
114  *            getNamespaceXXX(), nextTag()
115  *      </td>
116  *     </tr>
117  *     <tr>
118  *       <td> CHARACTERS  </td>
119  *       <td> next(), getTextXXX(), nextTag() </td>
120  *     </tr>
121  *     <tr>
122  *       <td> CDATA  </td>
123  *       <td> next(), getTextXXX(), nextTag() </td>
124  *     </tr>
125  *     <tr>
126  *       <td> COMMENT  </td>
127  *       <td> next(), getTextXXX(), nextTag() </td>
128  *     </tr>
129  *     <tr>
130  *       <td> SPACE  </td>
131  *       <td> next(), getTextXXX(), nextTag() </td>
132  *     </tr>
133  *     <tr>
134  *       <td> START_DOCUMENT  </td>
135  *       <td> next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(),
136  *            getCharacterEncodingScheme(), nextTag()</td>
137  *     </tr>
138  *     <tr>
139  *       <td> END_DOCUMENT  </td>
140  *       <td> close()</td>
141  *     </tr>
142  *     <tr>
143  *       <td> PROCESSING_INSTRUCTION  </td>
144  *       <td> next(), getPITarget(), getPIData(), nextTag() </td>
145  *     </tr>
146  *     <tr>
147  *       <td> ENTITY_REFERENCE  </td>
148  *       <td> next(), getLocalName(), getText(), nextTag() </td>
149  *     </tr>
150  *     <tr>
151  *       <td> DTD  </td>
152  *       <td> next(), getText(), nextTag() </td>
153  *     </tr>
154  *   </tbody>
155  *  </table>
156  *
157  * @version 1.0
158  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
159  * @see javax.xml.stream.events.XMLEvent
160  * @see XMLInputFactory
161  * @see XMLStreamWriter
162  * @since 1.6
163  */
164 public interface XMLStreamReader extends XMLStreamConstants {
165   /**
166    * Get the value of a feature/property from the underlying implementation
167    * @param name The name of the property, may not be null
168    * @return The value of the property
169    * @throws IllegalArgumentException if name is null
170    */
171   public Object getProperty(java.lang.String name) throws java.lang.IllegalArgumentException;
172 
173   /**
174    * Get next parsing event - a processor may return all contiguous
175    * character data in a single chunk, or it may split it into several chunks.
176    * If the property javax.xml.stream.isCoalescing is set to true
177    * element content must be coalesced and only one CHARACTERS event
178    * must be returned for contiguous element content or
179    * CDATA Sections.
180    *
181    * By default entity references must be
182    * expanded and reported transparently to the application.
183    * An exception will be thrown if an entity reference cannot be expanded.
184    * If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.
185    *
186    * <p>Given the following XML:<br>
187    * &lt;foo>&lt;!--description-->content text&lt;![CDATA[&lt;greeting>Hello&lt;/greeting>]]>other content&lt;/foo><br>
188    * The behavior of calling next() when being on foo will be:<br>
189    * 1- the comment (COMMENT)<br>
190    * 2- then the characters section (CHARACTERS)<br>
191    * 3- then the CDATA section (another CHARACTERS)<br>
192    * 4- then the next characters section (another CHARACTERS)<br>
193    * 5- then the END_ELEMENT<br>
194    *
195    * <p><b>NOTE:</b> empty element (such as &lt;tag/>) will be reported
196    *  with  two separate events: START_ELEMENT, END_ELEMENT - This preserves
197    *   parsing equivalency of empty element to &lt;tag>&lt;/tag>.
198    *
199    * This method will throw an IllegalStateException if it is called after hasNext() returns false.
200    * @see javax.xml.stream.events.XMLEvent
201    * @return the integer code corresponding to the current parse event
202    * @throws NoSuchElementException if this is called when hasNext() returns false
203    * @throws XMLStreamException  if there is an error processing the underlying XML source
204    */
205   public int next() throws XMLStreamException;
206 
207   /**
208    * Test if the current event is of the given type and if the namespace and name match the current
209    * namespace and name of the current event.  If the namespaceURI is null it is not checked for equality,
210    * if the localName is null it is not checked for equality.
211    * @param type the event type
212    * @param namespaceURI the uri of the event, may be null
213    * @param localName the localName of the event, may be null
214    * @throws XMLStreamException if the required values are not matched.
215    */
216   public void require(int type, String namespaceURI, String localName) throws XMLStreamException;
217 
218   /**
219    * Reads the content of a text-only element, an exception is thrown if this is
220    * not a text-only element.
221    * Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
222    * <br /> Precondition: the current event is START_ELEMENT.
223    * <br /> Postcondition: the current event is the corresponding END_ELEMENT.
224    *
225    * <br />The method does the following (implementations are free to optimized
226    * but must do equivalent processing):
227    * <pre>
228    * if(getEventType() != XMLStreamConstants.START_ELEMENT) {
229    * throw new XMLStreamException(
230    * "parser must be on START_ELEMENT to read next text", getLocation());
231    * }
232    * int eventType = next();
233    * StringBuffer content = new StringBuffer();
234    * while(eventType != XMLStreamConstants.END_ELEMENT ) {
235    * if(eventType == XMLStreamConstants.CHARACTERS
236    * || eventType == XMLStreamConstants.CDATA
237    * || eventType == XMLStreamConstants.SPACE
238    * || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
239    * buf.append(getText());
240    * } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
241    * || eventType == XMLStreamConstants.COMMENT) {
242    * // skipping
243    * } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
244    * throw new XMLStreamException(
245    * "unexpected end of document when reading element text content", this);
246    * } else if(eventType == XMLStreamConstants.START_ELEMENT) {
247    * throw new XMLStreamException(
248    * "element text content may not contain START_ELEMENT", getLocation());
249    * } else {
250    * throw new XMLStreamException(
251    * "Unexpected event type "+eventType, getLocation());
252    * }
253    * eventType = next();
254    * }
255    * return buf.toString();
256    * </pre>
257    *
258    * @throws XMLStreamException if the current event is not a START_ELEMENT
259    * or if a non text element is encountered
260    */
261   public String getElementText() throws XMLStreamException;
262 
263   /**
264    * Skips any white space (isWhiteSpace() returns true), COMMENT,
265    * or PROCESSING_INSTRUCTION,
266    * until a START_ELEMENT or END_ELEMENT is reached.
267    * If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT
268    * are encountered, an exception is thrown. This method should
269    * be used when processing element-only content seperated by white space.
270    *
271    * <br /> Precondition: none
272    * <br /> Postcondition: the current event is START_ELEMENT or END_ELEMENT
273    * and cursor may have moved over any whitespace event.
274    *
275    * <br />Essentially it does the following (implementations are free to optimized
276    * but must do equivalent processing):
277    * <pre>
278    * int eventType = next();
279    * while((eventType == XMLStreamConstants.CHARACTERS &amp;&amp; isWhiteSpace()) // skip whitespace
280    * || (eventType == XMLStreamConstants.CDATA &amp;&amp; isWhiteSpace())
281    * // skip whitespace
282    * || eventType == XMLStreamConstants.SPACE
283    * || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
284    * || eventType == XMLStreamConstants.COMMENT
285    * ) {
286    * eventType = next();
287    * }
288    * if (eventType != XMLStreamConstants.START_ELEMENT &amp;&amp; eventType != XMLStreamConstants.END_ELEMENT) {
289    * throw new String XMLStreamException("expected start or end tag", getLocation());
290    * }
291    * return eventType;
292    * </pre>
293    *
294    * @return the event type of the element read (START_ELEMENT or END_ELEMENT)
295    * @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION,
296    * START_ELEMENT or END_ELEMENT
297    * @throws NoSuchElementException if this is called when hasNext() returns false
298    */
299   public int nextTag() throws XMLStreamException;
300 
301   /**
302    * Returns true if there are more parsing events and false
303    * if there are no more events.  This method will return
304    * false if the current state of the XMLStreamReader is
305    * END_DOCUMENT
306    * @return true if there are more events, false otherwise
307    * @throws XMLStreamException if there is a fatal error detecting the next state
308    */
309   public boolean hasNext() throws XMLStreamException;
310 
311   /**
312    * Frees any resources associated with this Reader.  This method does not close the
313    * underlying input source.
314    * @throws XMLStreamException if there are errors freeing associated resources
315    */
316   public void close() throws XMLStreamException;
317 
318   /**
319    * Return the uri for the given prefix.
320    * The uri returned depends on the current state of the processor.
321    *
322    * <p><strong>NOTE:</strong>The 'xml' prefix is bound as defined in
323    * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a>
324    * specification to "http://www.w3.org/XML/1998/namespace".
325    *
326    * <p><strong>NOTE:</strong> The 'xmlns' prefix must be resolved to following namespace
327    * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>
328    * @param prefix The prefix to lookup, may not be null
329    * @return the uri bound to the given prefix or null if it is not bound
330    * @throws IllegalArgumentException if the prefix is null
331    */
332   public String getNamespaceURI(String prefix);
333 
334   /**
335    * Returns true if the cursor points to a start tag (otherwise false)
336    * @return true if the cursor points to a start tag, false otherwise
337    */
338   public boolean isStartElement();
339 
340   /**
341    * Returns true if the cursor points to an end tag (otherwise false)
342    * @return true if the cursor points to an end tag, false otherwise
343    */
344   public boolean isEndElement();
345 
346   /**
347    * Returns true if the cursor points to a character data event
348    * @return true if the cursor points to character data, false otherwise
349    */
350   public boolean isCharacters();
351 
352   /**
353    * Returns true if the cursor points to a character data event
354    * that consists of all whitespace
355    * @return true if the cursor points to all whitespace, false otherwise
356    */
357   public boolean isWhiteSpace();
358 
359 
360   /**
361    * Returns the normalized attribute value of the
362    * attribute with the namespace and localName
363    * If the namespaceURI is null the namespace
364    * is not checked for equality
365    * @param namespaceURI the namespace of the attribute
366    * @param localName the local name of the attribute, cannot be null
367    * @return returns the value of the attribute , returns null if not found
368    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
369    */
370   public String getAttributeValue(String namespaceURI,
371                                   String localName);
372 
373   /**
374    * Returns the count of attributes on this START_ELEMENT,
375    * this method is only valid on a START_ELEMENT or ATTRIBUTE.  This
376    * count excludes namespace definitions.  Attribute indices are
377    * zero-based.
378    * @return returns the number of attributes
379    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
380    */
381   public int getAttributeCount();
382 
383   /** Returns the qname of the attribute at the provided index
384    *
385    * @param index the position of the attribute
386    * @return the QName of the attribute
387    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
388    */
389   public QName getAttributeName(int index);
390 
391   /**
392    * Returns the namespace of the attribute at the provided
393    * index
394    * @param index the position of the attribute
395    * @return the namespace URI (can be null)
396    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
397    */
398   public String getAttributeNamespace(int index);
399 
400   /**
401    * Returns the localName of the attribute at the provided
402    * index
403    * @param index the position of the attribute
404    * @return the localName of the attribute
405    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
406    */
407   public String getAttributeLocalName(int index);
408 
409   /**
410    * Returns the prefix of this attribute at the
411    * provided index
412    * @param index the position of the attribute
413    * @return the prefix of the attribute
414    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
415    */
416   public String getAttributePrefix(int index);
417 
418   /**
419    * Returns the XML type of the attribute at the provided
420    * index
421    * @param index the position of the attribute
422    * @return the XML type of the attribute
423    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
424    */
425   public String getAttributeType(int index);
426 
427   /**
428    * Returns the value of the attribute at the
429    * index
430    * @param index the position of the attribute
431    * @return the attribute value
432    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
433    */
434   public String getAttributeValue(int index);
435 
436   /**
437    * Returns a boolean which indicates if this
438    * attribute was created by default
439    * @param index the position of the attribute
440    * @return true if this is a default attribute
441    * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
442    */
443   public boolean isAttributeSpecified(int index);
444 
445   /**
446    * Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT,
447    * this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE. On
448    * an END_ELEMENT the count is of the namespaces that are about to go
449    * out of scope.  This is the equivalent of the information reported
450    * by SAX callback for an end element event.
451    * @return returns the number of namespace declarations on this specific element
452    * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE
453    */
454   public int getNamespaceCount();
455 
456   /**
457    * Returns the prefix for the namespace declared at the
458    * index.  Returns null if this is the default namespace
459    * declaration
460    *
461    * @param index the position of the namespace declaration
462    * @return returns the namespace prefix
463    * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE
464    */
465   public String getNamespacePrefix(int index);
466 
467   /**
468    * Returns the uri for the namespace declared at the
469    * index.
470    *
471    * @param index the position of the namespace declaration
472    * @return returns the namespace uri
473    * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE
474    */
475   public String getNamespaceURI(int index);
476 
477   /**
478    * Returns a read only namespace context for the current
479    * position.  The context is transient and only valid until
480    * a call to next() changes the state of the reader.
481    * @return return a namespace context
482    */
483   public NamespaceContext getNamespaceContext();
484 
485   /**
486    * Returns a reader that points to the current start element
487    * and all of its contents.  Throws an XMLStreamException if the
488    * cursor does not point to a START_ELEMENT.<p>
489    * The sub stream is read from it MUST be read before the parent stream is
490    * moved on, if not any call on the sub stream will cause an XMLStreamException to be
491    * thrown.   The parent stream will always return the same result from next()
492    * whatever is done to the sub stream.
493    * @return an XMLStreamReader which points to the next element
494    */
495   //  public XMLStreamReader subReader() throws XMLStreamException;
496 
497   /**
498    * Allows the implementation to reset and reuse any underlying tables
499    */
500   //  public void recycle() throws XMLStreamException;
501 
502   /**
503    * Returns an integer code that indicates the type
504    * of the event the cursor is pointing to.
505    */
506   public int getEventType();
507 
508   /**
509    * Returns the current value of the parse event as a string,
510    * this returns the string value of a CHARACTERS event,
511    * returns the value of a COMMENT, the replacement value
512    * for an ENTITY_REFERENCE, the string value of a CDATA section,
513    * the string value for a SPACE event,
514    * or the String value of the internal subset of the DTD.
515    * If an ENTITY_REFERENCE has been resolved, any character data
516    * will be reported as CHARACTERS events.
517    * @return the current text or null
518    * @throws java.lang.IllegalStateException if this state is not
519    * a valid text state.
520    */
521   public String getText();
522 
523   /**
524    * Returns an array which contains the characters from this event.
525    * This array should be treated as read-only and transient. I.e. the array will
526    * contain the text characters until the XMLStreamReader moves on to the next event.
527    * Attempts to hold onto the character array beyond that time or modify the
528    * contents of the array are breaches of the contract for this interface.
529    * @return the current text or an empty array
530    * @throws java.lang.IllegalStateException if this state is not
531    * a valid text state.
532    */
533   public char[] getTextCharacters();
534 
535   /**
536    * Gets the the text associated with a CHARACTERS, SPACE or CDATA event.
537    * Text starting a "sourceStart" is copied into "target" starting at "targetStart".
538    * Up to "length" characters are copied.  The number of characters actually copied is returned.
539    *
540    * The "sourceStart" argument must be greater or equal to 0 and less than or equal to
541    * the number of characters associated with the event.  Usually, one requests text starting at a "sourceStart" of 0.
542    * If the number of characters actually copied is less than the "length", then there is no more text.
543    * Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
544    *
545    *<code>
546    * int length = 1024;
547    * char[] myBuffer = new char[ length ];
548    *
549    * for ( int sourceStart = 0 ; ; sourceStart += length )
550    * {
551    *    int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );
552    *
553    *   if (nCopied < length)
554    *       break;
555    * }
556    * </code>
557    * XMLStreamException may be thrown if there are any XML errors in the underlying source.
558    * The "targetStart" argument must be greater than or equal to 0 and less than the length of "target",
559    * Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".
560    *
561    * @param sourceStart the index of the first character in the source array to copy
562    * @param target the destination array
563    * @param targetStart the start offset in the target array
564    * @param length the number of characters to copy
565    * @return the number of characters actually copied
566    * @throws XMLStreamException if the underlying XML source is not well-formed
567    * @throws IndexOutOfBoundsException if targetStart < 0 or > than the length of target
568    * @throws IndexOutOfBoundsException if length < 0 or targetStart + length > length of target
569    * @throws UnsupportedOperationException if this method is not supported
570    * @throws NullPointerException is if target is null
571    */
572    public int getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
573      throws XMLStreamException;
574 
575   /**
576    * Gets the text associated with a CHARACTERS, SPACE or CDATA event.  Allows the underlying
577    * implementation to return the text as a stream of characters.  The reference to the
578    * Reader returned by this method is only valid until next() is called.
579    *
580    * All characters must have been checked for well-formedness.
581    *
582    * <p> This method is optional and will throw UnsupportedOperationException if it is not supported.
583    * @throws UnsupportedOperationException if this method is not supported
584    * @throws IllegalStateException if this is not a valid text state
585    */
586   //public Reader getTextStream();
587 
588   /**
589    * Returns the offset into the text character array where the first
590    * character (of this text event) is stored.
591    * @throws java.lang.IllegalStateException if this state is not
592    * a valid text state.
593    */
594   public int getTextStart();
595 
596   /**
597    * Returns the length of the sequence of characters for this
598    * Text event within the text character array.
599    * @throws java.lang.IllegalStateException if this state is not
600    * a valid text state.
601    */
602   public int getTextLength();
603 
604   /**
605    * Return input encoding if known or null if unknown.
606    * @return the encoding of this instance or null
607    */
608   public String getEncoding();
609 
610   /**
611    * Return true if the current event has text, false otherwise
612    * The following events have text:
613    * CHARACTERS,DTD ,ENTITY_REFERENCE, COMMENT, SPACE
614    */
615   public boolean hasText();
616 
617   /**
618    * Return the current location of the processor.
619    * If the Location is unknown the processor should return
620    * an implementation of Location that returns -1 for the
621    * location and null for the publicId and systemId.
622    * The location information is only valid until next() is
623    * called.
624    */
625   public Location getLocation();
626 
627   /**
628    * Returns a QName for the current START_ELEMENT or END_ELEMENT event
629    * @return the QName for the current START_ELEMENT or END_ELEMENT event
630    * @throws IllegalStateException if this is not a START_ELEMENT or
631    * END_ELEMENT
632    */
633   public QName getName();
634 
635   /**
636    * Returns the (local) name of the current event.
637    * For START_ELEMENT or END_ELEMENT returns the (local) name of the current element.
638    * For ENTITY_REFERENCE it returns entity name.
639    * The current event must be START_ELEMENT or END_ELEMENT,
640    * or ENTITY_REFERENCE
641    * @return the localName
642    * @throws IllegalStateException if this not a START_ELEMENT,
643    * END_ELEMENT or ENTITY_REFERENCE
644    */
645   public String getLocalName();
646 
647   /**
648    * returns true if the current event has a name (is a START_ELEMENT or END_ELEMENT)
649    * returns false otherwise
650    */
651   public boolean hasName();
652 
653   /**
654    * If the current event is a START_ELEMENT or END_ELEMENT  this method
655    * returns the URI of the prefix or the default namespace.
656    * Returns null if the event does not have a prefix.
657    * @return the URI bound to this elements prefix, the default namespace, or null
658    */
659   public String getNamespaceURI();
660 
661   /**
662    * Returns the prefix of the current event or null if the event does not have a prefix
663    * @return the prefix or null
664    */
665   public String getPrefix();
666 
667   /**
668    * Get the xml version declared on the xml declaration
669    * Returns null if none was declared
670    * @return the XML version or null
671    */
672   public String getVersion();
673 
674   /**
675    * Get the standalone declaration from the xml declaration
676    * @return true if this is standalone, or false otherwise
677    */
678   public boolean isStandalone();
679 
680   /**
681    * Checks if standalone was set in the document
682    * @return true if standalone was set in the document, or false otherwise
683    */
684   public boolean standaloneSet();
685 
686   /**
687    * Returns the character encoding declared on the xml declaration
688    * Returns null if none was declared
689    * @return the encoding declared in the document or null
690    */
691   public String getCharacterEncodingScheme();
692 
693   /**
694    * Get the target of a processing instruction
695    * @return the target or null
696    */
697   public String getPITarget();
698 
699   /**
700    * Get the data section of a processing instruction
701    * @return the data or null
702    */
703   public String getPIData();
704 }