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