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
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 * 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 }