StAX

Streaming API for XML (StAX) is an application programming interface (API) to read and write XML documents, originating from the Java programming language community.

Traditionally, XML APIs are either:

Both have advantages; the former (for example, DOM) allows for random access to the document, the latter (e.g. SAX) requires a small memory footprint and is typically much faster.

These two access metaphors can be thought of as polar opposites. A tree based API allows unlimited, random access and manipulation, while an event based API is a 'one shot' pass through the source document.

StAX was designed as a median between these two opposites. In the StAX metaphor, the programmatic entry point is a cursor that represents a point within the document. The application moves the cursor forward - 'pulling' the information from the parser as it needs. This is different from an event based API - such as SAX - which 'pushes' data to the application - requiring the application to maintain state between events as necessary to keep track of location within the document.

Contents

Origins

StAX has its roots in a number of incompatible pull APIs for XML, most notably XMLPULL, the authors of which (Stefan Haustein and Aleksander Slominski) collaborated with, amongst others, BEA Systems, Oracle, Sun, Breeze Factor and James Clark.

Examples

From JSR-173 Specification• Final, V1.0 (used under fair use).

Quote:

The following Java API shows the main methods for reading XML in the cursor approach.
public interface XMLStreamReader { 
  public int next() throws XMLStreamException; 
  public boolean hasNext() throws XMLStreamException; 
  public String getText(); 
  public String getLocalName(); 
  public String getNamespaceURI(); 
  // ...other methods not shown 
}
The writing side of the API has methods that correspond to the reading side for “StartElement” and “EndElement” event types.
public interface XMLStreamWriter { 
  public void writeStartElement(String localName) throws XMLStreamException;
  public void writeEndElement() throws XMLStreamException; 
  public void writeCharacters(String text) throws XMLStreamException; 
  // ...other methods not shown 
}
5.3.1 XMLStreamReader
This example illustrates how to instantiate an input factory, create a reader and iterate over the elements of an XML document.
XMLInputFactory xmlInputFactory = XMLInputFactory.newInstance(); 
XMLStreamReader xmlStreamReader = xmlInputFactory.createXMLStreamReader(...); 
while (xmlStreamReader.hasNext()) { 
    xmlStreamReader.next(); 
}

See also

Competing and complementary ways to process XML in Java (ordered loosely based on initial date of introduction):

External links

Implementations
Utilities and add-ons
Parsers built on top of StAX
Non-standard StAX-like parsers
Non-Java XML pull parsers
Articles and resources
Download JSR specification document as a pdf here: download now