1/* 2 * Copyright (c) 2009, 2017, 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 26package javax.xml.stream; 27 28import javax.xml.namespace.NamespaceContext; 29import 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 */ 165public 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 * This method will throw an IllegalStateException if it is called after hasNext() returns false. 201 * @see javax.xml.stream.events.XMLEvent 202 * @return the integer code corresponding to the current parse event 203 * @throws java.util.NoSuchElementException if this is called when hasNext() returns false 204 * @throws XMLStreamException if there is an error processing the underlying XML source 205 */ 206 public int next() throws XMLStreamException; 207 208 /** 209 * Test if the current event is of the given type and if the namespace and name match the current 210 * namespace and name of the current event. If the namespaceURI is null it is not checked for equality, 211 * if the localName is null it is not checked for equality. 212 * @param type the event type 213 * @param namespaceURI the uri of the event, may be null 214 * @param localName the localName of the event, may be null 215 * @throws XMLStreamException if the required values are not matched. 216 */ 217 public void require(int type, String namespaceURI, String localName) throws XMLStreamException; 218 219 /** 220 * Reads the content of a text-only element, an exception is thrown if this is 221 * not a text-only element. 222 * Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content. 223 * <br> Precondition: the current event is START_ELEMENT. 224 * <br> Postcondition: the current event is the corresponding END_ELEMENT. 225 * 226 * <br>The method does the following (implementations are free to optimized 227 * but must do equivalent processing): 228 * <pre> 229 * if(getEventType() != XMLStreamConstants.START_ELEMENT) { 230 * throw new XMLStreamException( 231 * "parser must be on START_ELEMENT to read next text", getLocation()); 232 * } 233 * 234 * int eventType = next(); 235 * StringBuffer content = new StringBuffer(); 236 * while(eventType != XMLStreamConstants.END_ELEMENT) { 237 * if(eventType == XMLStreamConstants.CHARACTERS 238 * || eventType == XMLStreamConstants.CDATA 239 * || eventType == XMLStreamConstants.SPACE 240 * || eventType == XMLStreamConstants.ENTITY_REFERENCE) { 241 * buf.append(getText()); 242 * } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION 243 * || eventType == XMLStreamConstants.COMMENT) { 244 * // skipping 245 * } else if(eventType == XMLStreamConstants.END_DOCUMENT) { 246 * throw new XMLStreamException( 247 * "unexpected end of document when reading element text content", this); 248 * } else if(eventType == XMLStreamConstants.START_ELEMENT) { 249 * throw new XMLStreamException( 250 * "element text content may not contain START_ELEMENT", getLocation()); 251 * } else { 252 * throw new XMLStreamException( 253 * "Unexpected event type "+eventType, getLocation()); 254 * } 255 * eventType = next(); 256 * } 257 * return buf.toString(); 258 * </pre> 259 * 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} 718