Java Doc for XMLStreamReader.java in  » 6.0-JDK-Modules » jsr173-Stax » javax » xml » stream » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The XMLStreamReader is designed to iterate over XML using next() and hasNext(). The data can be accessed using methods such as getEventType(), getNamespaceURI(), getLocalName() and getText();

The next() method causes the reader to read the next parse event. The next() method returns an integer which identifies the type of event just read.

The event type can be determined using getEventType().

Parsing events are defined as the XML Declaration, a DTD, start tag, character data, white space, end tag, comment, or processing instruction. An attribute or namespace event may be encountered at the root level of a document as the result of a query operation.

For XML 1.0 compliance an XML processor must pass the identifiers of declared unparsed entities, notation declarations and their associated identifiers to the application. This information is 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 List l = (List) getProperty("javax.xml.stream.notations"); The following call will return a list of entity declarations: 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.

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 java.lang.IllegalStateException.

Valid methods for each state
Event Type	Valid Methods
All States	getProperty(), hasNext(), require(), close(), getNamespaceURI(), isStartElement(), isEndElement(), isCharacters(), isWhiteSpace(), getNamespaceContext(), getEventType(),getLocation(), hasText(), hasName()
START_ELEMENT	next(), getName(), getLocalName(), hasName(), getPrefix(), getAttributeXXX(), isAttributeSpecified(), getNamespaceXXX(), getElementText(), nextTag()
ATTRIBUTE	next(), nextTag() getAttributeXXX(), isAttributeSpecified(),
NAMESPACE	next(), nextTag() getNamespaceXXX()
END_ELEMENT	next(), getName(), getLocalName(), hasName(), getPrefix(), getNamespaceXXX(), nextTag()
CHARACTERS	next(), getTextXXX(), nextTag()
CDATA	next(), getTextXXX(), nextTag()
COMMENT	next(), getTextXXX(), nextTag()
SPACE	next(), getTextXXX(), nextTag()
START_DOCUMENT	next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(), getCharacterEncodingScheme(), nextTag()
END_DOCUMENT	close()
PROCESSING_INSTRUCTION	next(), getPITarget(), getPIData(), nextTag()
ENTITY_REFERENCE	next(), getLocalName(), getText(), nextTag()
DTD	next(), getText(), nextTag()

version:
   1.0
author:
   Copyright (c) 2003 by BEA Systems. All Rights Reserved.
See Also:   javax.xml.stream.events.XMLEvent
See Also:   XMLInputFactory
See Also:   XMLStreamWriter

 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());
 } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
 || eventType == XMLStreamConstants.COMMENT) {
 // skipping
 } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
 throw new XMLStreamException(
 "unexpected end of document when reading element text content", this);
 } else if(eventType == XMLStreamConstants.START_ELEMENT) {
 throw new XMLStreamException(
 "element text content may not contain START_ELEMENT", getLocation());
 } else {
 throw new XMLStreamException(
 "Unexpected event type "+eventType, getLocation());
 }
 eventType = next();
 }
 return buf.toString();
 

NOTE:The 'xml' prefix is bound as defined in Namespaces in XML specification to "http://www.w3.org/XML/1998/namespace".

NOTE: The 'xmlns' prefix must be resolved to following namespace http://www.w3.org/2000/xmlns/
Parameters:
  prefix - The prefix to lookup, may not be null the uri bound to the given prefix or null if it is not bound
throws:
  IllegalArgumentException - if the prefix is null

Given the following XML:
<foo><!--description-->content text<![CDATA[<greeting>Hello</greeting>]]>other content</foo>
The behavior of calling next() when being on foo will be:
1- the comment (COMMENT)
2- then the characters section (CHARACTERS)
3- then the CDATA section (another CHARACTERS)
4- then the next characters section (another CHARACTERS)
5- then the END_ELEMENT

NOTE: 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 Also:   javax.xml.stream.events.XMLEvent 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

 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;