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