< prev index next >
src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java
Print this page
*** 55,67 ****
* provided through the property API on this interface.
* The following two properties allow access to this information:
* javax.xml.stream.notations and javax.xml.stream.entities.
* When the current event is a DTD the following call will return a
* list of Notations
! * <code>List l = (List) getProperty("javax.xml.stream.notations");</code>
* The following call will return a list of entity declarations:
! * <code>List l = (List) getProperty("javax.xml.stream.entities");</code>
* These properties can only be accessed during a DTD event and
* are defined to return null if the information is not available.
*
* <p>The following table describes which methods are valid in what state.
* If a method is called in an invalid state the method will throw a
--- 55,67 ----
* provided through the property API on this interface.
* The following two properties allow access to this information:
* javax.xml.stream.notations and javax.xml.stream.entities.
* When the current event is a DTD the following call will return a
* list of Notations
! * {@code List l = (List) getProperty("javax.xml.stream.notations");}
* The following call will return a list of entity declarations:
! * {@code List l = (List) getProperty("javax.xml.stream.entities");}
* These properties can only be accessed during a DTD event and
* are defined to return null if the information is not available.
*
* <p>The following table describes which methods are valid in what state.
* If a method is called in an invalid state the method will throw a
*** 95,110 ****
* getAttributeXXX(), isAttributeSpecified(),
* getNamespaceXXX(),
* getElementText(), nextTag()
* </td>
* </tr>
* <td> ATTRIBUTE </td>
* <td> next(), nextTag()
* getAttributeXXX(), isAttributeSpecified(),
* </td>
* </tr>
! * </tr>
* <td> NAMESPACE </td>
* <td> next(), nextTag()
* getNamespaceXXX()
* </td>
* </tr>
--- 95,111 ----
* getAttributeXXX(), isAttributeSpecified(),
* getNamespaceXXX(),
* getElementText(), nextTag()
* </td>
* </tr>
+ * <tr>
* <td> ATTRIBUTE </td>
* <td> next(), nextTag()
* getAttributeXXX(), isAttributeSpecified(),
* </td>
* </tr>
! * <tr>
* <td> NAMESPACE </td>
* <td> next(), nextTag()
* getNamespaceXXX()
* </td>
* </tr>
*** 182,207 ****
* expanded and reported transparently to the application.
* An exception will be thrown if an entity reference cannot be expanded.
* If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.
*
* <p>Given the following XML:<br>
! * <foo><!--description-->content text<![CDATA[<greeting>Hello</greeting>]]>other content</foo><br>
* The behavior of calling next() when being on foo will be:<br>
* 1- the comment (COMMENT)<br>
* 2- then the characters section (CHARACTERS)<br>
* 3- then the CDATA section (another CHARACTERS)<br>
* 4- then the next characters section (another CHARACTERS)<br>
* 5- then the END_ELEMENT<br>
*
! * <p><b>NOTE:</b> empty element (such as <tag/>) will be reported
* with two separate events: START_ELEMENT, END_ELEMENT - This preserves
! * parsing equivalency of empty element to <tag></tag>.
*
* This method will throw an IllegalStateException if it is called after hasNext() returns false.
* @see javax.xml.stream.events.XMLEvent
* @return the integer code corresponding to the current parse event
! * @throws NoSuchElementException if this is called when hasNext() returns false
* @throws XMLStreamException if there is an error processing the underlying XML source
*/
public int next() throws XMLStreamException;
/**
--- 183,208 ----
* expanded and reported transparently to the application.
* An exception will be thrown if an entity reference cannot be expanded.
* If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.
*
* <p>Given the following XML:<br>
! * {@code <foo><!--description-->content text<![CDATA[<greeting>Hello>/greeting>]]>other content>/foo>}<br>
* The behavior of calling next() when being on foo will be:<br>
* 1- the comment (COMMENT)<br>
* 2- then the characters section (CHARACTERS)<br>
* 3- then the CDATA section (another CHARACTERS)<br>
* 4- then the next characters section (another CHARACTERS)<br>
* 5- then the END_ELEMENT<br>
*
! * <p><b>NOTE:</b> empty element (such as {@code <tag/>}) will be reported
* with two separate events: START_ELEMENT, END_ELEMENT - This preserves
! * parsing equivalency of empty element to {@code <tag></tag>}.
*
* This method will throw an IllegalStateException if it is called after hasNext() returns false.
* @see javax.xml.stream.events.XMLEvent
* @return the integer code corresponding to the current parse event
! * @throws java.util.NoSuchElementException if this is called when hasNext() returns false
* @throws XMLStreamException if there is an error processing the underlying XML source
*/
public int next() throws XMLStreamException;
/**
*** 217,239 ****
/**
* Reads the content of a text-only element, an exception is thrown if this is
* not a text-only element.
* Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
! * <br /> Precondition: the current event is START_ELEMENT.
! * <br /> Postcondition: the current event is the corresponding END_ELEMENT.
*
! * <br />The method does the following (implementations are free to optimized
* but must do equivalent processing):
* <pre>
* if(getEventType() != XMLStreamConstants.START_ELEMENT) {
* throw new XMLStreamException(
* "parser must be on START_ELEMENT to read next text", getLocation());
* }
* int eventType = next();
* StringBuffer content = new StringBuffer();
! * while(eventType != XMLStreamConstants.END_ELEMENT ) {
* if(eventType == XMLStreamConstants.CHARACTERS
* || eventType == XMLStreamConstants.CDATA
* || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
* buf.append(getText());
--- 218,241 ----
/**
* Reads the content of a text-only element, an exception is thrown if this is
* not a text-only element.
* Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
! * <br> Precondition: the current event is START_ELEMENT.
! * <br> Postcondition: the current event is the corresponding END_ELEMENT.
*
! * <br>The method does the following (implementations are free to optimized
* but must do equivalent processing):
* <pre>
* if(getEventType() != XMLStreamConstants.START_ELEMENT) {
* throw new XMLStreamException(
* "parser must be on START_ELEMENT to read next text", getLocation());
* }
+ *
* int eventType = next();
* StringBuffer content = new StringBuffer();
! * while(eventType != XMLStreamConstants.END_ELEMENT) {
* if(eventType == XMLStreamConstants.CHARACTERS
* || eventType == XMLStreamConstants.CDATA
* || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
* buf.append(getText());
*** 266,302 ****
* until a START_ELEMENT or END_ELEMENT is reached.
* If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT
* are encountered, an exception is thrown. This method should
* be used when processing element-only content seperated by white space.
*
! * <br /> Precondition: none
! * <br /> Postcondition: the current event is START_ELEMENT or END_ELEMENT
* and cursor may have moved over any whitespace event.
*
! * <br />Essentially it does the following (implementations are free to optimized
* but must do equivalent processing):
! * <pre>
* int eventType = next();
! * while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
! * || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
* // skip whitespace
* || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
* || eventType == XMLStreamConstants.COMMENT
* ) {
* eventType = next();
* }
! * if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
* throw new String XMLStreamException("expected start or end tag", getLocation());
* }
! * return eventType;
* </pre>
*
* @return the event type of the element read (START_ELEMENT or END_ELEMENT)
* @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION,
* START_ELEMENT or END_ELEMENT
! * @throws NoSuchElementException if this is called when hasNext() returns false
*/
public int nextTag() throws XMLStreamException;
/**
* Returns true if there are more parsing events and false
--- 268,304 ----
* until a START_ELEMENT or END_ELEMENT is reached.
* If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT
* are encountered, an exception is thrown. This method should
* be used when processing element-only content seperated by white space.
*
! * <br> Precondition: none
! * <br> Postcondition: the current event is START_ELEMENT or END_ELEMENT
* and cursor may have moved over any whitespace event.
*
! * <br>Essentially it does the following (implementations are free to optimized
* but must do equivalent processing):
! * <pre> {@code
* int eventType = next();
! * while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
! * || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
* // skip whitespace
* || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
* || eventType == XMLStreamConstants.COMMENT
* ) {
* eventType = next();
* }
! * if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
* throw new String XMLStreamException("expected start or end tag", getLocation());
* }
! * return eventType; }
* </pre>
*
* @return the event type of the element read (START_ELEMENT or END_ELEMENT)
* @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION,
* START_ELEMENT or END_ELEMENT
! * @throws java.util.NoSuchElementException if this is called when hasNext() returns false
*/
public int nextTag() throws XMLStreamException;
/**
* Returns true if there are more parsing events and false
*** 540,573 ****
* The "sourceStart" argument must be greater or equal to 0 and less than or equal to
* the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0.
* If the number of characters actually copied is less than the "length", then there is no more text.
* Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
*
! *<code>
* int length = 1024;
* char[] myBuffer = new char[ length ];
*
* for ( int sourceStart = 0 ; ; sourceStart += length )
* {
* int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );
*
* if (nCopied < length)
* break;
* }
! * </code>
* XMLStreamException may be thrown if there are any XML errors in the underlying source.
* The "targetStart" argument must be greater than or equal to 0 and less than the length of "target",
* Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".
*
* @param sourceStart the index of the first character in the source array to copy
* @param target the destination array
* @param targetStart the start offset in the target array
* @param length the number of characters to copy
* @return the number of characters actually copied
* @throws XMLStreamException if the underlying XML source is not well-formed
! * @throws IndexOutOfBoundsException if targetStart < 0 or > than the length of target
! * @throws IndexOutOfBoundsException if length < 0 or targetStart + length > length of target
* @throws UnsupportedOperationException if this method is not supported
* @throws NullPointerException is if target is null
*/
public int getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
throws XMLStreamException;
--- 542,575 ----
* The "sourceStart" argument must be greater or equal to 0 and less than or equal to
* the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0.
* If the number of characters actually copied is less than the "length", then there is no more text.
* Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
*
! * <pre>{@code
* int length = 1024;
* char[] myBuffer = new char[ length ];
*
* for ( int sourceStart = 0 ; ; sourceStart += length )
* {
* int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );
*
* if (nCopied < length)
* break;
* }
! * } </pre>
* XMLStreamException may be thrown if there are any XML errors in the underlying source.
* The "targetStart" argument must be greater than or equal to 0 and less than the length of "target",
* Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".
*
* @param sourceStart the index of the first character in the source array to copy
* @param target the destination array
* @param targetStart the start offset in the target array
* @param length the number of characters to copy
* @return the number of characters actually copied
* @throws XMLStreamException if the underlying XML source is not well-formed
! * @throws IndexOutOfBoundsException if targetStart {@literal <} 0 or {@literal >} than the length of target
! * @throws IndexOutOfBoundsException if length {@literal <} 0 or targetStart + length {@literal >} length of target
* @throws UnsupportedOperationException if this method is not supported
* @throws NullPointerException is if target is null
*/
public int getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
throws XMLStreamException;
< prev index next >