Does StAX Stack Up?

Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

There is a new XML API in town called StAX (Streaming API for XML). With SAX (Simple API for XML), DOM (Document Object Model), and TrAX (Transformation API for XML), do we really need another API in the JAXP (Java API for XML Processing) family for processing XML documents? I would argue, yes.

In this article, we’ll discuss how StAX can be more developer friendly than SAX and how it can perform better than DOM and TrAX for certain use cases. We’ll discuss where to download the reference implementation, and how to configure the classpath for your first StAX project. Then, we’ll develop simple programs to read and write XML documents using StAX. Finally, we’ll summarize our first experience with StAX.

How Does StAX Stack Up?

Where does StAX fit in with its sister API for processing XML documents?

Despite its name, SAX isn’t all that simple. In fact, it’s kind of awkward at first. The developer writes a handler class that receives event callbacks. It is a “push” type of API that requires reading the entire XML document. SAX is strictly an API for reading XML documents. You must learn another API to write XML documents.

DOM is a very powerful API that can be used to create, query, and manipulate XML documents. However, it requires an in-memory representation of the document, which can be costly in terms of performance.

TrAX is an API for transforming source documents into result documents using XSLT (XML Stylesheet Language for Transformations), a declarative, rule-based language. As with DOM, a performance penalty may be paid for its significant power.

How does StAX stack up? StAX is even simpler than SAX. It is a “pull” API that gives parsing control to the developer by exposing an iterator-based API and an underlying stream of events^[i]. It has an API to read and write XML documents more efficiently than DOM or TrAX.

StAX won’t replace its sister API. It doesn’t have the power of DOM and TrAX. It can’t expose arbitrary data structures as XML as SAX can. But, it can handle certain XML use cases more efficiently or simply than its predecessors. We’ll discuss which API is suited to a given use case in a future article. Let’s get grounded in StAX before we make comparisons.

Downloading and Configuring StAX

The StAX API was developed as part of the Java Community Process and is JSR-173. The API Specification can be downloaded from http://jcp.org/en/jsr/detail?id=173. The reference implementation can be downloaded from http://dev2dev.bea.com/technologies/stax/index.jsp.

There is a runtime dependency of the reference implementation on Java 1.4 for its new non-blocking I/O capabilities that can be downloaded at http://java.sun.com.

You will find the following jars in the reference implementation download that you should include in your classpath:

Learning to Read and Write

Now that we have the reference implementation of StAX downloaded and ready to use, let’s learn how to read and write XML documents with StAX. We’ll begin by first writing an XML document, and then we’ll echo it back.

SimpleXmlWriter

SimpleXmlWriter will live up to its name by being a very simple example of how to write an XML document. We begin by importing classes from the new javax.xml.stream package, as well as old standbys from java.io.

package com.developer.stax;

import java.io.FileWriter;
import java.io.IOException;

import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;

We begin by getting an instance of the XMLOutputFactory. Then, we ask the factory for an XMLStreamWriter that wraps a FileWriter object for the passed filename.

public class SimpleXmlWriter
{
   public static void main(String args[])
      throws IOException, XMLStreamException
   {
      String filename = args[0];

      XMLOutputFactory factory = XMLOutputFactory.newInstance();

      XMLStreamWriter writer =
         factory.createXMLStreamWriter(new FileWriter(filename));

The XMLStreamWriter has methods for writing elements, attributes, and data to an XML document. The stream writing API provides writeStartXxx() and writeEndXxx() methods for the document itself, and for elements; they need to come in pairs. The indenting in the following example helps to show the matching pairs.

   writer.writeStartDocument();
     writer.writeStartElement("Customers");
       writer.writeStartElement("Customer");
         writer.writeStartElement("Name");
         writer.writeCharacters("ABC Pizza");
         writer.writeEndElement();
         writer.writeStartElement("Address");
         writer.writeCharacters("1 Main Street");
         writer.writeEndElement();
         writer.writeStartElement("City");
         writer.writeCharacters("Simsbury");
         writer.writeEndElement();
         writer.writeStartElement("State");
         writer.writeCharacters("CT");
         writer.writeEndElement();
         writer.writeStartElement("Zip");
         writer.writeCharacters("06070");
         writer.writeEndElement();
       writer.writeEndElement();
     writer.writeEndElement();
   writer.writeEndDocument();
   writer.flush();

   SimpleXmlReader.main(args);
   }
}

The flush() method at the end is needed to write the document and close the FileWriter.

Sample Output

Here is our first XML document created via StAX:

<?xml version="1.0" encoding="utf-8"?>
<Customers>
   <Customer>
      <Name>ABC Pizza</Name>
      <Address>1 Main Street</Address>
      <City>Simsbury</City>
      <State>CT</State>
      <Zip>06070</Zip>
   </Customer>
</Customers>

SimpleXMLReader

Now, let’s read the document we just created. This time, we import classes from the reading side of the API from javax.xml.stream and some old standby from java.io.

package com.developer.stax;

import java.io.FileNotFoundException;
import java.io.FileReader;

import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;

We begin by getting an instance of an XMLInputFactory. Then, we ask the factory for an XMLStreamReader that wraps a FileReader object for the passed filename.

public class SimpleXmlReader
{
   public static void main(String[] args)
      throws FileNotFoundException, XMLStreamException
   {
      String filename = args[0];

      XMLInputFactory factory = XMLInputFactory.newInstance();

      XMLStreamReader reader =
         factory.createXMLStreamReader(new FileReader(filename));

The iterator-based API for reading streams is very familiar to Java developers. There is a hasNext() as well as a next() method. In this example, we use hasNext() to iterate through the entire document. Start and End elements are echoed to the output stream via getText(). Data is also output using getText(); however, whitespace is ignored. After the cursor has iterated over the entire stream, we close the XMLStreamReader.

      while (reader.hasNext())
      {
         if (reader.isStartElement() || reader.isEndElement())
         {
            System.out.print(reader.getText());
         }
         else if (reader.isCharacters() && !reader.isWhiteSpace())
         {
            System.out.print(reader.getText());
         }
         reader.next();
      }
      reader.close();
   }
}

Sample Code

The sample code can be downloaded here.

Summary

StAX is a new addition to the JAXP family. It may be easier to use than SAX, and more efficient than DOM and TrAX, although it is less powerful. We developed very simple classes for reading and writing documents through the streaming API. In future articles, we’ll delve deeper into StAX. Until then, the rest is up to you!

About the Author

Jeff Ryan is an enterprise architect for Hartford Financial Services. He has twenty years experience designing, developing, and delivering automated solutions to business problems. His current focus is on Java, XML, and Service Oriented Architecture. He may be reached at jeffreyjryan@aol.com.

[i] Java Community Process http://jcp.org, Streaming API for XML JSR-173 Specification Version 1.0, October 2003