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