Java StAX: XMLStreamReader - The Cursor API

XML Stream Events
XML Event Processing

Jakob Jenkov
Last update: 2014-05-21

The XMLStreamReader class in Java StAX provides a Cursor style API for parsing XML. Like the Iterator API it allows you to move from event to event in the XML, letting you control when to move to the next event. An "event" in this case is for instance the beginning of an element, the end of an element, a group of text etc. In other words, pretty much the same events you would get from a SAX parser.

To read more about the difference between the Iterator and Cursor style API's, read the introduction to StAX: Java StAX Parser

You create an XMLStreamReader via the javax.xml.stream.XMLInputFactory class. Here is a Java XMLStreamReader example:

XMLInputFactory factory = XMLInputFactory.newInstance();

//get Reader connected to XML input from somewhere..
Reader reader = getXmlReader();

try {

    XMLStreamReader streamReader =
    factory.createXMLStreamReader(reader);
    
} catch (XMLStreamException e) {
    e.printStackTrace();
}

Once created you can iterate through the XML input from the underlying Reader. Here is how that looks:

XMLStreamReader streamReader = factory.createXMLStreamReader(
    new FileReader("data\\test.xml"));

while(streamReader.hasNext()){
    streamReader.next();
    if(streamReader.getEventType() == XMLStreamReader.START_ELEMENT){
        System.out.println(streamReader.getLocalName());
    }
}

You obtain the event type by calling the XMLStreamReader.getEventType() method. When you know the event type, you can process the given event as you need.

XML Stream Events

Below is a list of the events you can encounter in an XML stream. There are constants for each of these events in the javax.xml.stream.XMLStreamConstants interface.

ATTRIBUTE
CDATA
CHARACTERS
COMMENT
DTD
END_DOCUMENT
END_ELEMENT
ENTITY_DECLARATION
ENTITY_REFERENCE
NAMESPACE
NOTATION_DECLARATION
PROCESSING_INSTRUCTION
SPACE
START_DOCUMENT
START_ELEMENT

XML Event Processing

From the XMLStreamReader you can get access to the corresponding XML data. You can also get information about where (line number + column number) in the XML stream the event was encountered.

Next: Java StAX: XMLStreamWriter - The Cursor Writer API

Tweet
	Jakob Jenkov