1 /*
2 * Copyright (c) 2009, 2018, 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 * @throws XMLStreamException if the current event is not a START_ELEMENT
260 * or if a non text element is encountered
261 */
262 public String getElementText() throws XMLStreamException;
263
264 /**
265 * Skips any white space (isWhiteSpace() returns true), COMMENT,
266 * or PROCESSING_INSTRUCTION,
267 * until a START_ELEMENT or END_ELEMENT is reached.
268 * If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT
269 * are encountered, an exception is thrown. This method should
270 * be used when processing element-only content seperated by white space.
271 *
272 * <br> Precondition: none
273 * <br> Postcondition: the current event is START_ELEMENT or END_ELEMENT
274 * and cursor may have moved over any whitespace event.
275 *
276 * <br>Essentially it does the following (implementations are free to optimized
277 * but must do equivalent processing):
278 * <pre> {@code
279 * int eventType = next();
280 * while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
281 * || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
282 * // skip whitespace
283 * || eventType == XMLStreamConstants.SPACE
284 * || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
285 * || eventType == XMLStreamConstants.COMMENT
286 * ) {
287 * eventType = next();
288 * }
289 * if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
290 * throw new String XMLStreamException("expected start or end tag", getLocation());
291 * }
292 * return eventType; }
293 * </pre>
294 *
295 * @return the event type of the element read (START_ELEMENT or END_ELEMENT)
296 * @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION,
297 * START_ELEMENT or END_ELEMENT
298 * @throws java.util.NoSuchElementException if this is called when hasNext() returns false
299 */
300 public int nextTag() throws XMLStreamException;
301
302 /**
303 * Returns true if there are more parsing events and false
304 * if there are no more events. This method will return
305 * false if the current state of the XMLStreamReader is
306 * END_DOCUMENT
307 * @return true if there are more events, false otherwise
308 * @throws XMLStreamException if there is a fatal error detecting the next state
309 */
310 public boolean hasNext() throws XMLStreamException;
311
312 /**
313 * Frees any resources associated with this Reader. This method does not close the
314 * underlying input source.
315 * @throws XMLStreamException if there are errors freeing associated resources
316 */
317 public void close() throws XMLStreamException;
318
319 /**
320 * Return the uri for the given prefix.
321 * The uri returned depends on the current state of the processor.
322 *
323 * <p><strong>NOTE:</strong>The 'xml' prefix is bound as defined in
324 * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a>
325 * specification to "http://www.w3.org/XML/1998/namespace".
326 *
327 * <p><strong>NOTE:</strong> The 'xmlns' prefix must be resolved to following namespace
328 * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>
329 * @param prefix The prefix to lookup, may not be null
330 * @return the uri bound to the given prefix or null if it is not bound
331 * @throws IllegalArgumentException if the prefix is null
332 */
333 public String getNamespaceURI(String prefix);
334
335 /**
336 * Returns true if the cursor points to a start tag (otherwise false)
337 * @return true if the cursor points to a start tag, false otherwise
338 */
339 public boolean isStartElement();
340
341 /**
342 * Returns true if the cursor points to an end tag (otherwise false)
343 * @return true if the cursor points to an end tag, false otherwise
344 */
345 public boolean isEndElement();
346
347 /**
348 * Returns true if the cursor points to a character data event
349 * @return true if the cursor points to character data, false otherwise
350 */
351 public boolean isCharacters();
352
353 /**
354 * Returns true if the cursor points to a character data event
355 * that consists of all whitespace
356 * @return true if the cursor points to all whitespace, false otherwise
357 */
358 public boolean isWhiteSpace();
359
360
361 /**
362 * Returns the normalized attribute value of the
363 * attribute with the namespace and localName
364 * If the namespaceURI is null the namespace
365 * is not checked for equality
366 * @param namespaceURI the namespace of the attribute
367 * @param localName the local name of the attribute, cannot be null
368 * @return returns the value of the attribute , returns null if not found
369 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
370 */
371 public String getAttributeValue(String namespaceURI,
372 String localName);
373
374 /**
375 * Returns the count of attributes on this START_ELEMENT,
376 * this method is only valid on a START_ELEMENT or ATTRIBUTE. This
377 * count excludes namespace definitions. Attribute indices are
378 * zero-based.
379 * @return returns the number of attributes
380 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
381 */
382 public int getAttributeCount();
383
384 /** Returns the qname of the attribute at the provided index
385 *
386 * @param index the position of the attribute
387 * @return the QName of the attribute
388 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
389 */
390 public QName getAttributeName(int index);
391
392 /**
393 * Returns the namespace of the attribute at the provided
394 * index
395 * @param index the position of the attribute
396 * @return the namespace URI (can be null)
397 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
398 */
399 public String getAttributeNamespace(int index);
400
401 /**
402 * Returns the localName of the attribute at the provided
403 * index
404 * @param index the position of the attribute
405 * @return the localName of the attribute
406 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
407 */
408 public String getAttributeLocalName(int index);
409
410 /**
411 * Returns the prefix of this attribute at the
412 * provided index
413 * @param index the position of the attribute
414 * @return the prefix of the attribute
415 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
416 */
417 public String getAttributePrefix(int index);
418
419 /**
420 * Returns the XML type of the attribute at the provided
421 * index
422 * @param index the position of the attribute
423 * @return the XML type of the attribute
424 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
425 */
426 public String getAttributeType(int index);
427
428 /**
429 * Returns the value of the attribute at the
430 * index
431 * @param index the position of the attribute
432 * @return the attribute value
433 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
434 */
435 public String getAttributeValue(int index);
436
437 /**
438 * Returns a boolean which indicates if this
439 * attribute was created by default
440 * @param index the position of the attribute
441 * @return true if this is a default attribute
442 * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
443 */
444 public boolean isAttributeSpecified(int index);
445
446 /**
447 * Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT,
448 * this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE. On
449 * an END_ELEMENT the count is of the namespaces that are about to go
450 * out of scope. This is the equivalent of the information reported
451 * by SAX callback for an end element event.
452 * @return returns the number of namespace declarations on this specific element
453 * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE
454 */
455 public int getNamespaceCount();
456
457 /**
458 * Returns the prefix for the namespace declared at the
459 * index. Returns null if this is the default namespace
460 * declaration
461 *
462 * @param index the position of the namespace declaration
463 * @return returns the namespace prefix
464 * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE
465 */
466 public String getNamespacePrefix(int index);
467
468 /**
469 * Returns the uri for the namespace declared at the
470 * index.
471 *
472 * @param index the position of the namespace declaration
473 * @return returns the namespace uri
474 * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE
475 */
476 public String getNamespaceURI(int index);
477
478 /**
479 * Returns a read only namespace context for the current
480 * position. The context is transient and only valid until
481 * a call to next() changes the state of the reader.
482 * @return return a namespace context
483 */
484 public NamespaceContext getNamespaceContext();
485
486 /**
487 * Returns a reader that points to the current start element
488 * and all of its contents. Throws an XMLStreamException if the
489 * cursor does not point to a START_ELEMENT.<p>
490 * The sub stream is read from it MUST be read before the parent stream is
491 * moved on, if not any call on the sub stream will cause an XMLStreamException to be
492 * thrown. The parent stream will always return the same result from next()
493 * whatever is done to the sub stream.
494 * @return an XMLStreamReader which points to the next element
495 */
496 // public XMLStreamReader subReader() throws XMLStreamException;
497
498 /**
499 * Allows the implementation to reset and reuse any underlying tables
500 */
501 // public void recycle() throws XMLStreamException;
502
503 /**
504 * Returns an integer code that indicates the type of the event the cursor is
505 * pointing to. The initial event type is {@link #START_DOCUMENT}.
506 *
507 * @return the type of the current event
508 */
509 public int getEventType();
510
511 /**
512 * Returns the current value of the parse event as a string,
513 * this returns the string value of a CHARACTERS event,
514 * returns the value of a COMMENT, the replacement value
515 * for an ENTITY_REFERENCE, the string value of a CDATA section,
516 * the string value for a SPACE event,
517 * or the String value of the internal subset of the DTD.
518 * If an ENTITY_REFERENCE has been resolved, any character data
519 * will be reported as CHARACTERS events.
520 * @return the current text or null
521 * @throws java.lang.IllegalStateException if this state is not
522 * a valid text state.
523 */
524 public String getText();
525
526 /**
527 * Returns an array which contains the characters from this event.
528 * This array should be treated as read-only and transient. I.e. the array will
529 * contain the text characters until the XMLStreamReader moves on to the next event.
530 * Attempts to hold onto the character array beyond that time or modify the
531 * contents of the array are breaches of the contract for this interface.
532 * @return the current text or an empty array
533 * @throws java.lang.IllegalStateException if this state is not
534 * a valid text state.
535 */
536 public char[] getTextCharacters();
537
538 /**
539 * Gets the the text associated with a CHARACTERS, SPACE or CDATA event.
540 * Text starting a "sourceStart" is copied into "target" starting at "targetStart".
541 * Up to "length" characters are copied. The number of characters actually copied is returned.
542 *
543 * The "sourceStart" argument must be greater or equal to 0 and less than or equal to
544 * the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0.
545 * If the number of characters actually copied is less than the "length", then there is no more text.
546 * Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
547 *
548 * <pre>{@code
549 * int length = 1024;
550 * char[] myBuffer = new char[ length ];
551 *
552 * for ( int sourceStart = 0 ; ; sourceStart += length )
553 * {
554 * int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );
555 *
556 * if (nCopied < length)
557 * break;
558 * }
559 * } </pre>
560 * XMLStreamException may be thrown if there are any XML errors in the underlying source.
561 * The "targetStart" argument must be greater than or equal to 0 and less than the length of "target",
562 * Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".
563 *
564 * @param sourceStart the index of the first character in the source array to copy
565 * @param target the destination array
566 * @param targetStart the start offset in the target array
567 * @param length the number of characters to copy
568 * @return the number of characters actually copied
569 * @throws XMLStreamException if the underlying XML source is not well-formed
570 * @throws IndexOutOfBoundsException if targetStart {@literal <} 0 or {@literal >} than the length of target
571 * @throws IndexOutOfBoundsException if length {@literal <} 0 or targetStart + length {@literal >} length of target
572 * @throws UnsupportedOperationException if this method is not supported
573 * @throws NullPointerException is if target is null
574 */
575 public int getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
576 throws XMLStreamException;
577
578 /**
579 * Gets the text associated with a CHARACTERS, SPACE or CDATA event. Allows the underlying
580 * implementation to return the text as a stream of characters. The reference to the
581 * Reader returned by this method is only valid until next() is called.
582 *
583 * All characters must have been checked for well-formedness.
584 *
585 * <p> This method is optional and will throw UnsupportedOperationException if it is not supported.
586 * @throws UnsupportedOperationException if this method is not supported
587 * @throws IllegalStateException if this is not a valid text state
588 */
589 //public Reader getTextStream();
590
591 /**
592 * Returns the offset into the text character array where the first
593 * character (of this text event) is stored.
594 *
595 * @return the starting position of the text in the character array
596 * @throws java.lang.IllegalStateException if this state is not
597 * a valid text state.
598 */
599 public int getTextStart();
600
601 /**
602 * Returns the length of the sequence of characters for this
603 * Text event within the text character array.
604 *
605 * @return the length of the text
606 * @throws java.lang.IllegalStateException if this state is not
607 * a valid text state.
608 */
609 public int getTextLength();
610
611 /**
612 * Return input encoding if known or null if unknown.
613 * @return the encoding of this instance or null
614 */
615 public String getEncoding();
616
617 /**
618 * Return a boolean indicating whether the current event has text.
619 * The following events have text:
620 * CHARACTERS,DTD ,ENTITY_REFERENCE, COMMENT, SPACE
621 *
622 * @return true if the event has text, false otherwise
623 */
624 public boolean hasText();
625
626 /**
627 * Return the current location of the processor.
628 * If the Location is unknown the processor should return
629 * an implementation of Location that returns -1 for the
630 * location and null for the publicId and systemId.
631 * The location information is only valid until next() is
632 * called.
633 * @return the location of the cursor
634 */
635 public Location getLocation();
636
637 /**
638 * Returns a QName for the current START_ELEMENT or END_ELEMENT event
639 * @return the QName for the current START_ELEMENT or END_ELEMENT event
640 * @throws IllegalStateException if this is not a START_ELEMENT or
641 * END_ELEMENT
642 */
643 public QName getName();
644
645 /**
646 * Returns the (local) name of the current event.
647 * For START_ELEMENT or END_ELEMENT returns the (local) name of the current element.
648 * For ENTITY_REFERENCE it returns entity name.
649 * The current event must be START_ELEMENT or END_ELEMENT,
650 * or ENTITY_REFERENCE
651 * @return the localName
652 * @throws IllegalStateException if this not a START_ELEMENT,
653 * END_ELEMENT or ENTITY_REFERENCE
654 */
655 public String getLocalName();
656
657 /**
658 * returns a boolean indicating whether the current event has a name
659 * (is a START_ELEMENT or END_ELEMENT).
660 *
661 * @return true if the event has a name, false otherwise
662 */
663 public boolean hasName();
664
665 /**
666 * If the current event is a START_ELEMENT or END_ELEMENT this method
667 * returns the URI of the prefix or the default namespace.
668 * Returns null if the event does not have a prefix.
669 * @return the URI bound to this elements prefix, the default namespace, or null
670 */
671 public String getNamespaceURI();
672
673 /**
674 * Returns the prefix of the current event or null if the event does not have a prefix
675 * @return the prefix or null
676 */
677 public String getPrefix();
678
679 /**
680 * Get the xml version declared on the xml declaration
681 * Returns null if none was declared
682 * @return the XML version or null
683 */
684 public String getVersion();
685
686 /**
687 * Get the standalone declaration from the xml declaration
688 * @return true if this is standalone, or false otherwise
689 */
690 public boolean isStandalone();
691
692 /**
693 * Checks if standalone was set in the document
694 * @return true if standalone was set in the document, or false otherwise
695 */
696 public boolean standaloneSet();
697
698 /**
699 * Returns the character encoding declared on the xml declaration
700 * Returns null if none was declared
701 * @return the encoding declared in the document or null
702 */
703 public String getCharacterEncodingScheme();
704
705 /**
706 * Get the target of a processing instruction
707 * @return the target or null
708 */
709 public String getPITarget();
710
711 /**
712 * Get the data section of a processing instruction
713 * @return the data or null
714 */
715 public String getPIData();
716 }