XML.com: XML From the Inside Out
oreilly.comSafari Bookshelf.Conferences.


An Introduction to StAX

September 17, 2003

Most current XML APIs fall into one of two broad classes: event-based APIs like SAX and XNI or tree-based APIs like DOM and JDOM. Most programmers find the tree-based APIs to be easier to use; but such APIs are less efficient, especially with respect to memory usage. An in-memory tree tends to be several times larger than the document it models. Thus tree APIs are normally not practical for documents larger than a few megabytes in size or in memory constrained environments such as J2ME. In these situations, a streaming API such as SAX or XNI is normally preferred. A streaming API uses much less memory than a tree API since it doesn't have to hold the entire document in memory simultaneously. It can process the document in small pieces. Furthermore, streaming APIs are fast. They can start generating output from the input almost immediately, without waiting for the entire document to be read. They don't have to build excessively complicated tree data structures they'll just pull apart again into smaller pieces. However, the common streaming APIs like SAX are all push APIs. They feed the content of the document to the application as soon as they see it, whether the application is ready to receive that data or not. SAX and XNI are fast and efficient, but the patterns they require programmers to adopt are unfamiliar and uncomfortable to many developers.

Pull APIs are a more comfortable alternative for streaming processing of XML. A pull API is based around the more familiar iterator design pattern rather than the less well-known observer design pattern. In a pull API, the client program asks the parser for the next piece of information rather than the parser telling the client program when the next datum is available. In a pull API the client program drives the parser. In a push API the parser drives the client.

Just a tad more than a year ago, I wrote an article for XML.com discussing what until now has been the primary pull API, XMLPULL. This article identified a number of problems with XMLPULL. The last two paragraphs of that article summed up:

These problems are not casual bugs. They are deliberate design decisions, based on a desire to reduce the footprint of XMLPULL to the minimum possible for J2ME environments. None of these problems are likely to be fixed in the future. The trade-offs made in the name of size may be acceptable if you're working in J2ME. They are completely unacceptable in a desktop or server environment. Thus XMLPULL seems destined to remain a niche API for developers seeking efficiency at all costs.

Nonetheless, there are some interesting ideas here. Most importantly, the problems I've identified stem from implementation issues, not from anything fundamental to a pull-based model for XML processing. A future pull-API that learned from XMLPULL's mistakes could easily become a real alternative to SAX and DOM.

Now it's a year later, and I am very pleased to report that the next generation API is here. BEA Systems, working in conjunction with Sun, XMLPULL developers Stefan Haustein and Aleksandr Slominski, XML heavyweight James Clark, and others in the Java Community Process are on the verge of releasing StAX, the Streaming API for XML. StAX is a pull parsing API for XML which avoids most of the pitfalls I noted in XMLPULL. XMLPULL was a nice proof of concept. StAX is suitable for real work.

Like SAX, StAX is a parser independent, pure Java API based on interfaces that can be implemented by multiple parsers. Currently there is only one implementation, the reference implementation bundled with the draft specification. You can download it here. Several more are likely to be developed as soon as the spec is complete.

StAX shares with SAX the ability to read arbitrarily large documents. However, in StAX the application is in control rather than the parser. The application tells the parser when it wants to receive the next data chunk rather than the parser telling the client when the next chunk of data is ready. Furthermore, StAX exceeds SAX by allowing programs to both read existing XML documents and create new ones. Unlike SAX, StAX is a bidirectional API.

Reading Documents with StAX

XMLStreamReader is the key interface in StAX. This interface represents a cursor that's moved across an XML document from beginning to end. At any given time, this cursor points at one thing: a text node, a start-tag, a comment, the beginning of the document, etc. The cursor always moves forward, never backward, and normally only moves one item at a time. You invoke methods such as getName and getText on the XMLStreamReader to retrieve information about the item the cursor is currently positioned at.

A typical StAX program begins by using the XMLInputFactory class to load an implementation dependent instance of XMLStreamReader:

URL u = new URL("http://www.cafeconleche.org/");
InputStream in = u.openStream();
XMLInputFactory factory = XMLInputFactory.newInstance();
XMLStreamReader parser = factory.createXMLStreamReader(in);

You can also create an XMLStreamReader from a java.io.Reader or a javax.xml.transform.Source. You can't create, surprisingly, one from a URL, either a java.net.URL object or a string containing a URL.

If anything goes wrong, an XMLStreamException, a checked exception, is thrown.

Now it's time to actually read the document. The next method in XMLStreamReader advances the cursor to the next item. Various getter methods to extract data from the current item. Some of the most important of these getters include

public QName    getName()
public String   getLocalName()
public String   getNamespaceURI()
public String   getText()
public String   getElementText()
public int      getEventType()
public Location getLocation()
public int      getAttributeCount()
public QName    getAttributeName(int index)
public String   getAttributeValue(String namespaceURI, String localName)

For example, here's a simple bit of code that iterates through an XML document and prints out the names of the different elements it encounters:

while (true) {
    int event = parser.next();
    if (event == XMLStreamConstants.END_DOCUMENT) {
    if (event == XMLStreamConstants.START_ELEMENT) {

Here's the beginning of the output when I ran this across a simple well-formed HTML file:


Not all of the getter methods work all the time. For instance, if the cursor is positioned on an end-tag, then you can get the name and namespace but not the attributes or the element text. If the cursor is positioned on a text node, then you can get the text but not the name, namespace, prefix, or attributes. Text nodes just don't have these things. Calling an inapplicable method normally returns null. To find out what kind of node the parser is currently positioned on, you call the getEventType method. This returns one of these seventeen int constants:

  • XMLStreamConstants.START_DOCUMENT
  • XMLStreamConstants.END_DOCUMENT
  • XMLStreamConstants.START_ELEMENT
  • XMLStreamConstants.END_ELEMENT
  • XMLStreamConstants.ATTRIBUTE
  • XMLStreamConstants.CHARACTERS
  • XMLStreamConstants.CDATA
  • XMLStreamConstants.SPACE
  • XMLStreamConstants.COMMENT
  • XMLStreamConstants.DTD
  • XMLStreamConstants.START_ENTITY
  • XMLStreamConstants.END_ENTITY
  • XMLStreamConstants.NAMESPACE

For a slightly more realistic example, consider an outliner program that reads through an XHTML document and prints out the contents of all the heading elements: h1, h2, h3, and so forth. A for loop calls the next method until the end of the document is seen. Each event is tested for its type. If the event is a start-tag and its name indicates it's a heading such as h1, then the inHeader int flag is incremented. If the event is a header end-tag, then the inHeader int flag is decremented. If the event is a characters event and inHeader is greater than 0, then the content of the characters event is printed. All other events are ignored.

import javax.xml.stream.*;
import java.net.URL;
import java.io.*;

public class XHTMLOutliner {

  public static void main(String[] args) {

    if (args.length == 0) {
      System.err.println("Usage: java XHTMLOutliner url" );
    String input = args[0];

    try {
      URL u = new URL(input);
      InputStream in = u.openStream();
      XMLInputFactory factory = XMLInputFactory.newInstance();
      XMLStreamReader parser = factory.createXMLStreamReader(in);
      int inHeader = 0;
      for (int event = parser.next();  
       event != XMLStreamConstants.END_DOCUMENT;
       event = parser.next()) {
        switch (event) {
          case XMLStreamConstants.START_ELEMENT:
            if (isHeader(parser.getLocalName())) {
          case XMLStreamConstants.END_ELEMENT:
            if (isHeader(parser.getLocalName())) {
              if (inHeader == 0) System.out.println();
          case XMLStreamConstants.CHARACTERS:
            if (inHeader > 0)  System.out.print(parser.getText());
          case XMLStreamConstants.CDATA:
            if (inHeader > 0)  System.out.print(parser.getText());
        } // end switch
      } // end while
    catch (XMLStreamException ex) {
    catch (IOException ex) {
      System.out.println("IOException while parsing " + input);


    * Determine if this is an XHTML heading element or not
    * @param  name tag name
    * @return boolean true if this is h1, h2, h3, h4, h5, or h6; 
    *                 false otherwise
    private static boolean isHeader(String name) {
      if (name.equals("h1")) return true;
      if (name.equals("h2")) return true;
      if (name.equals("h3")) return true;
      if (name.equals("h4")) return true;
      if (name.equals("h5")) return true;
      if (name.equals("h6")) return true;
      return false;


The loop with a switch statement is a very common pattern in StAX. There are a few ways to filter the event stream; of course, you could use a stack of if-else statements instead of the switch, but almost all StAX programs will feature an event loop something like this one. This is probably my only major criticism of StAX. Integer type codes and big switch statements are relics of procedural thinking. Object oriented programs should be based around classes, inheritance hierarchies, and polymorphism instead. The next method should return an XMLEvent object that has subclasses like StartElement, Characters, and StartDocument instead. NekoPull is an API that does this the right way. The main reason to use integer type codes instead of classes is to avoid Java's very slow reflection API and instanceof operator. In my opinion, however, what really needs to be fixed is the speed of reflection, not the APIs that depend on it.

Pages: 1, 2

Next Pagearrow