StAX
Encyclopedia
Streaming API for XML is an application programming interface (API) to read and write XML
XML
Extensible Markup Language is a set of rules for encoding documents in machine-readable form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards....

 documents, originating from the Java programming language
Java (programming language)
Java is a programming language originally developed by James Gosling at Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities...

 community.

Traditionally, XML APIs are either:
  • DOM based - the entire document is read into memory as a tree structure for random access by the calling application
  • event based - the application registers to receive events as entities are encountered within the source document.

Both have advantages; the former (for example, DOM
Document Object Model
The Document Object Model is a cross-platform and language-independent convention for representing and interacting with objects in HTML, XHTML and XML documents. Aspects of the DOM may be addressed and manipulated within the syntax of the programming language in use...

) allows for random access to the document, the latter (e.g. SAX
Simple API for XML
SAX is an event-based sequential access parser API developed by the XML-DEV mailing list for XML documents. SAX provides a mechanism for reading data from an XML document that is an alternative to that provided by the Document Object Model...

) 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.

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
BEA Systems
BEA Systems, Inc. specialized in enterprise infrastructure software products known as "middleware", which connect software applications to databases and was acquired by Oracle Corporation on April 29, 2008.- History :...

, Oracle
Oracle Corporation
Oracle Corporation is an American multinational computer technology corporation that specializes in developing and marketing hardware systems and enterprise software products – particularly database management systems...

, Sun
Sun Microsystems
Sun Microsystems, Inc. was a company that sold :computers, computer components, :computer software, and :information technology services. Sun was founded on February 24, 1982...

, Breeze Factor and James Clark
James Clark (XML expert)
James Clark, is the author of groff and expat and has done much work with open-source software and XML. Born in London, and educated at Charterhouse and Merton College, Oxford, Clark has lived in Bangkok, Thailand since 1995, and is now a permanent resident...

.

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):
  • Document Object Model (DOM)
    Document Object Model
    The Document Object Model is a cross-platform and language-independent convention for representing and interacting with objects in HTML, XHTML and XML documents. Aspects of the DOM may be addressed and manipulated within the syntax of the programming language in use...

    , the first standardized, language/platform-independent tree-based XML processing model; alternate Java tree models include JDOM
    JDOM
    JDOM is an open source Java-based document object model for XML that was designed specifically for the Java platform so that it can take advantage of its language features. JDOM integrates with Document Object Model and Simple API for XML , supports XPath and XSLT. It uses external parsers to...

    , Dom4j
    Dom4j
    dom4j is an open source Java library for working with XML, XPath and XSLT. It is compatible with DOM, SAX and JAXP standards.The library is distributed under an BSD-style license.- Versions :...

    , and XOM
  • Simple API for XML (SAX)
    Simple API for XML
    SAX is an event-based sequential access parser API developed by the XML-DEV mailing list for XML documents. SAX provides a mechanism for reading data from an XML document that is an alternative to that provided by the Document Object Model...

    , the standard XML push API
  • Java XML Binding API (JAXB), works on top of another parser (usually streaming parser), binds contained data to/from Java objects.
  • Streaming XML
    Streaming XML
    Streaming XML means dynamic data which is in an XML format.Another popular use of this term refers to one method of consuming XML data – largely known as Simple API for XML. This is via asynchronous events that are generated as the XML data is parsed. In this context, the consumer streams through...


External links

Implementations

Utilities and add-ons
  • StAX-Utils Provides a set of utility classes that make it easy for developers to integrate StAX into their existing XML processing applications.
    • StAX-Utils includes classes to provide XML file indenting and formatting.
  • StaxMate is a light-weight framework that builds on top of Stax API and provides more convenient nested/filtered cursor for reading xml, nested outputters for writing xml (with optional indentation) and other tools (build DOM from Stax sources, write to Stax destinations) for interoperability.


Parsers built on top of StAX
  • Apache Axiom is a light weight XML object model based on top of Stax and also provides lazy object building.
  • Apache Pivot
    Apache Pivot
    Apache Pivot is an open-source platform for building rich web applications in Java or any JVM-compatible language. It is released under the Apache License version 2.0.-Architecture:Its classes are divided in the following categories:...

     uses StAX for the serialization of user interface markup written in WTKX.


Non-standard StAX-like parsers
  • XPP Parser based on the very similar but older XMLPull API.
  • kXML A Java Micro Edition parser that uses the XMLPull API.
  • Javolution
    Javolution
    Javolution is a real-time library aiming to make Java applications faster and more time predictable. Indeed, time-predictability can easily be ruined by the use of the standard library Javolution is a real-time library aiming to make Java applications faster and more time predictable. Indeed,...

     provides a real-time StAX-like implementation which does not force object creation (e.g. String) and has smaller effect on memory footprint/garbage collection (Note: to reduce object creation, most StAX implementations maintain lookup tables to retrieve and reuse frequently used String objects).
  • The XmlReader class in Microsoft
    Microsoft
    Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...

    's .NET Framework
    .NET Framework
    The .NET Framework is a software framework that runs primarily on Microsoft Windows. It includes a large library and supports several programming languages which allows language interoperability...

    is a pull-style XML parser.


Non-Java XML pull parsers
  • Qt has XML parser (QXmlStreamReader) and writer (QXmlStreamWriter)
  • irrXML is a simple and fast open source XML parser for C++
  • LlamaXML is the XML C++ pull parser and writer
  • libxml2 is the XML C parser and toolkit (MIT License)
  • Expat is an XML parser library written in C


Articles and resources
Download JSR specification document as a pdf here: download now
The source of this article is wikipedia, the free encyclopedia.  The text of this article is licensed under the GFDL.
 
x
OK