Introduction to StAX

StAX, the Streaming API for XML, is a new API for pull-parsing of XML, developed under the Java Community Process as JSR 173.   This blog gives an introduction to this API, which combines the efficiency of SAX with the ease of use of tree-based APIs.

Most of the XML parsers fall into two broad categories: tree based (e.g., DOM) or event based (e.g., SAX). Although StAX is   more closely aligned with the latter, it bridges the gap between the two. In SAX, data is pushed via events to application   code handlers. In StAX, the application “pulls” the data from the XML data stream at its convenience. Application code can   filter, skip tags, or stop parsing at any time. The application–not the parser–is in control, which enables a more   intuitive way to process data.

StAX API

The StAX API exposes methods for iterative, event-based processing of XML documents. XML documents are treated as a filtered   series of events, and infoset states can be stored in a procedural fashion. Moreover, unlike SAX, the StAX API is   bidirectional, enabling both reading and writing of XML documents.

  The StAX API is really two distinct API sets: a cursor API and an iterator API.

Cursor API

As the name implies, the StAX cursor API represents a cursor with which you can walk an XML document from beginning to end.   This cursor can point to one thing at a time, and always moves forward, never backward, usually one infoset element at a   time.

The two main cursor interfaces are XMLStreamReader and XMLStreamWriter.

XMLStreamReader

An Instance of XMLStreamReader is used to read the XML Content. The StAX API provides XMLInputFactory to create an instance   of XMLStreamReader.

FileInputStream fis = new FileInputStream(file);  XMLStreamReader xmlStAXStreamReader =          XMLInputFactory.newInstance().              createXMLStreamReader(fis);

By Calling the next method of XMLStreamReader, it emits one of the following events:

Depending on the event, one can get more information by calling other corresponding methods appropriate to the event. For   example, if the START_ELEMENT event is thrown, then calling getLocalName() will return the local name of the element.

XMLStreamWriter

An Instance of XMLStreamWriter is used to write the XML content to output. The StAX API provides XMLOutputFactory to create   an instance of XMLStreamWriter

FileOutputStream outputStream; // Initialize the stream  XMLStreamWriter xmlStAXStreamwriter = XMLOutputFactory.newInstance().          createXMLStreamWriter(outputStream);

Then this writer can be used to write events. For example:

To write a start element: writer.writeStartElement(“Name”)

To write an end element: writer.writeEndElement()

To write a comment: writer.writeComment(“This is a comment”)

Iterator API

The StAX iterator API represents an XML document stream as a set of discrete event objects. These events are pulled by the   application and provided by the parser in the order in which they are read in the source XML document.

The base iterator interface is called XMLEvent, and there are many other subinterfaces for each event type.The primary parser   interface for reading iterator events is XMLEventReader, and the primary interface for writing iterator events is   XMLEventWriter. The XMLEventReader  interface contains five methods, the most important of which is nextEvent(), which   returns the next event in an XML stream. XMLEventReader implements java.util.Iterator, which means that returns from

XMLEventReader can be cached or passed into routines that can work with the standard Java Iterator; for example:

public interface XMLEventReader extends Iterator {    public XMLEvent nextEvent() throws XMLStreamException;    public boolean hasNext();    public XMLEvent peek() throws XMLStreamException;    …  }

  Similarly, on the output side of the iterator API, you have:

  public interface XMLEventWriter {    public void flush() throws XMLStreamException;    public void close() throws XMLStreamException;    public void add(XMLEvent e) throws XMLStreamException;    public void add(Attribute attribute) \      throws XMLStreamException;    …  } 

Summing up, StAX XML Processing gives more control to the client application than to the parser, enabling much faster and   more memory-efficient processing.