Java StAX: XMLStreamReader - The Cursor API

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.

Jakob Jenkov

Featured Videos

Java Generics

Java ForkJoinPool

P2P Networks Introduction



















Close TOC
All Tutorial Trails
All Trails
Table of contents (TOC) for this tutorial trail
Trail TOC
Table of contents (TOC) for this tutorial
Page TOC
Previous tutorial in this tutorial trail
Previous
Next tutorial in this tutorial trail
Next