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


An Introduction to StAX
by Elliotte Rusty Harold | Pages: 1, 2

This simple example perhaps doesn't demonstrate the full power of StAX. Since the client application controls the process, it's easy to write separate methods for different elements. These methods can have detailed knowledge of the internal structure of the type of element they handle. For example, you could write one method that handles headers, one that handles img elements, one that handles tables, one that handles meta tags, and so forth. For example, you might process an html element that contains head and body child elements like this:

public void processHtml(XmlPullParser parser) {
  while (true) {
    int event = parser.next();
    if (event == XMLStreamConstants.START_ELEMENT) {
      if (parser.getLocalName().equals("head")) processHead(parser);
      else if (parser.getLocalName().equals("body")) processBody(parser)
    else if (event == XMLStreamConstants.END_ELEMENT) {// </html>

Here I'm making a lot of assumptions about exactly which tags appear where when. This isn't unusual in XML processing . Most programs are written with particular vocabularies in mind. You wouldn't expect an XHTML outliner to know what to do with a DocBook document, much less an SVG picture, for example. However, it is best to test and verify your expectations about data formats. Normally, this would be done through validation. You can turn on validation by setting the factory's javax.xml.stream.isValidating property to true before instantiating the parser like this:

factory.setProperty("javax.xml.stream.isValidating", Boolean.TRUE);

You would then register an XMLReporter with the XMLInputFactory to receive notices of the validity errors. For example, using an anonymous inner class,

factory.setXMLReporter(new XMLReporter() {
  public void report(String message, String errorType,
    Object relatedInformation, Location location) {
      System.err.println("Problem in " + location.getLocationURI());
      System.err.println("at line " + location.getLineNumber()
        + ", column " + location.getColumnNumber());

If you want validity errors to be fatal, throw an XMLStreamException from the report method rather than just printing the error message. However, StAX parsers are not required to be able to validate and the reference implementation can't, so this doesn't yet work.

StAX does offer an alternative for simple cases. If you expect a particular item to be present in the document, you can require it using a type and an optional name and namespace. For example, if I think that the cursor is positioned at an XHTML <head> start-tag, I'd require it thusly:


If my expectation proves wrong, then the require method throws an XMLStreamException, a checked exception. You can pass null for either the namespace or the element name to indicate that all namespaces and names are acceptable. Putting this all together, the general pattern might be something like:

try {
catch (XMLStreamException ex) {
  // Oops! The head was missing!


StAX is not limited to reading XML documents. It can also create them. For output, instead of an XMLStreamReader you use, naturally enough, an XMLStreamWriter. This interface provides methods to write elements, attributes, comments, text, and all the other parts of an XML document. An XMLStreamWriter is created by an XMLOutputFactory like this:

OutputStream out = new FileOutputStream("data.xml");
XMLOutputFactory factory = XMLOutputFactory.newInstance();
XMLStreamWriter writer = factory.createXMLStreamWriter(out);

You write data onto the stream by using various writeFOO methods: writeStartDocument, writeStartElement, writeEndElement, writeCharacters, writeComment, writeCDATA, etc. For example, these lines of code write a simple hello world document:

writer.writeStartDocument("ISO-8859-1", "1.0");
writer.writeAttribute("id", "g1");
writer.writeCharacters("Hello StAX");

When you've finished creating the document, you want to flush and close the writer. This does not close the underlying output stream, so you'll need to close that too:


XMLStreamWriter helps maintain some well-formedness constraints. For instance, endDocument closes all unclosed start-tags, and writeCharacters performs any necessary escaping of reserved characters like & and <. However, the checking is minimal. XMLStreamWriter allows documents with multiple roots, documents with more than one XML declaration, element names that contain whitespace, characters that don't exist in the output character set, and a lot more. Implementations are allowed but not required to check these things. The reference implementation does not check them. Separate verification and testing of the output is necessary. Creating XML documents with XMLStreamWriter is faster and more more efficient than serializing a DOM or XOM tree, but it's not nearly as robust.

Summing Up

This article has just skimmed along the surface of StAX; the API has more to offer than there is space here to describe. Like SAX, StAX enables pipelines that chain the output of one process to the input of the next. It can filter the documents it parses to modify or log the documents. It can support XML views of non-XML data. It can marshal data structures and objects into XML documents and it can unmarshal the documents back into objects.

When is StAX not appropriate? Basically whenever a streaming API doesn't work. Like SAX, StAX still requires you to build data structures as the document is parsed in order to hold onto information for any length of time. In the worst case, these data structures can become as large and complex as the original document. In these cases, a tree-based API such as DOM or XOM may be more appropriate. Such an API definitely provides more convenient random access to the tree than does StAX (or any other streaming API). StAX works well when you need to process a large document a small piece at a time moving from beginning to end, that is, when you can essentially slide a peephole over the complete document. It works less well when you need to access widely separated parts of the document at the same time in unpredictable orders. However, many of the toughest XML processing problems come from exactly the domain where StAX does work well.

StAX is a fast, potentially extremely fast, straight-forward, memory-thrifty way to loading data from an XML document the structure of which is well known in advance. State management is much simpler in StAX than in SAX, so if you find that the SAX logic is just getting way too complex to follow or debug, then StAX is well worth exploring. A few features such as validation, schema support, and entity resolution are either not available or are not functional in the current reference implementation, but these should soon be available in independent implementations. StAX will be a very useful addition to any Java developer's XML toolkit.

1 to 7 of 7
  1. Why "streaming" word is used in StAX?
    2007-03-22 02:55:51 vikas_khengare
  2. StAX, Streaming APIs and DOM
    2006-06-06 09:49:58 MichaelTrachtman
  3. I have a question about this acticle
    2004-01-29 09:20:33 Jeff Wong
  4. bidirectional SAX
    2003-10-03 17:11:52 Taylor Cowan
  5. FYI: Patent pending
    2003-10-01 03:35:10 Marty Feldmann
  6. xmliter: another alternative
    2003-09-21 18:29:55 Mark Hayes
  7. Actually, StAX provides Event-Object based access!
    2003-09-18 06:23:57 Stefan Haustein
1 to 7 of 7