StAX API

Cursor API

Iterator API

Iterator Event Types

Example of Event Mapping

Choosing between Cursor and Iterator APIs

Development Goals

Comparing Cursor and Iterator APIs

StAX API

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

The StAX API is really two distinct API sets: acursor API andaniterator API. These two API sets explained in greater detail later inthis chapter, but their main features are briefly described below.

Cursor API

As the name implies, the StAXcursor API represents a cursor with whichyou can walk an XML document from beginning to end. This cursor canpoint to one thing at a time, and always moves forward, neverbackward, usually one infoset element at a time.

The two main cursor interfaces areXMLStreamReader andXMLStreamWriter.XMLStreamReader includes accessor methodsfor all possible information retrievable from the XML Information model, including document encoding,element names, attributes, namespaces, text nodes, start tags, comments, processing instructions, document boundaries, andso forth; for example:

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}

You can call methods onXMLStreamReader, such asgetText andgetName, toget data at the current cursor location.XMLStreamWriter provides methods that correspond toStartElementandEndElement event types; for example:

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}

The cursor API mirrors SAX in many ways. For example, methods areavailable for directly accessing string and character information, and integer indexes can be usedto access attribute and namespace information. As with SAX, the cursor API methodsreturn XML information as strings, which minimizes object allocation requirements.

Iterator API

The StAXiterator API represents an XML document stream as a set ofdiscrete event objects. These events are pulled by the application and provided bythe parser in the order in which they are read in the sourceXML document.

The base iterator interface is calledXMLEvent, and there are subinterfaces for eachevent type listed inTable 18-2. The primary parser interface for reading iteratorevents isXMLEventReader, and the primary interface for writing iterator events isXMLEventWriter. TheXMLEventReader interface contains five methods, the most important of which isnextEvent, which returns the next event in an XML stream.XMLEventReader implementsjava.util.Iterator,which means that returns fromXMLEventReader can be cached or passed intoroutines 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;    ...}

Iterator Event Types

Table 18-2 lists theXMLEvent types defined in the event iterator API.

Table 18-2XMLEvent Types

Note that theDTD,EntityDeclaration,EntityReference,NotationDeclaration, andProcessingInstruction events are onlycreated if the document being processed contains a DTD.

Example of Event Mapping

As an example of how the event iterator API maps an XMLstream, consider the following XML document:

<?xml version="1.0"?><BookCatalogue xmlns="http://www.publishing.org">    <Book>        <Title>Yogasana Vijnana: the Science of Yoga</Title>        <ISBN>81-40-34319-4</ISBN>        <Cost currency="INR">11.50</Cost>    </Book></BookCatalogue>

This document would be parsed into eighteen primary and secondary events, as showninTable 18-3. Note that secondary events, shown in curly braces ({}), are typically accessedfrom a primary event rather than directly.

Table 18-3 Example of Iterator API Event Mapping

version="1.0"

isCData = falsedata = "\n"IsWhiteSpace = true

qname = BookCatalogue:http://www.publishing.orgattributes = nullnamespaces = {BookCatalogue" -> http://www.publishing.org"}

qname = Bookattributes = nullnamespaces = null

qname = Titleattributes = nullnamespaces = null

isCData = falsedata = "Yogasana Vijnana: the Science of Yoga\n\t"IsWhiteSpace = false

qname = Titlenamespaces = null

qname = ISBNattributes = nullnamespaces = null

isCData = falsedata = "81-40-34319-4\n\t"IsWhiteSpace = false

qname = ISBNnamespaces = null

qname = Costattributes = {"currency" -> INR}namespaces = null

isCData = falsedata = "11.50\n\t"IsWhiteSpace = false

qname = Costnamespaces = null

isCData = falsedata = "\n"IsWhiteSpace = true

qname = Booknamespaces = null

isCData = falsedata = "\n"IsWhiteSpace = true

qname = BookCatalogue:http://www.publishing.orgnamespaces = {BookCatalogue" -> http://www.publishing.org"}

There are several important things to note in this example:

• The events are created in the order in which the corresponding XML elements are encountered in the document, including nesting of elements, opening and closing of elements, attribute order, document start and document end, and so forth.

• As with proper XML syntax, all container elements have corresponding start and end events; for example, everyStartElement has a correspondingEndElement, even for empty elements.

• Attribute events are treated as secondary events, and are accessed from their correspondingStartElement event.

• Similar toAttribute events,Namespace events are treated as secondary, but appear twice and are accessible twice in the event stream, first from their correspondingStartElement and then from their correspondingEndElement.

• Character events are specified for all elements, even if those elements have no character data. Similarly,Character events can be split across events.

• The StAX parser maintains a namespace stack, which holds information about all XML namespaces defined for the current element and its ancestors. The namespace stack, which is exposed through thejavax.xml.namespace.NamespaceContext interface, can be accessed by namespace prefix or URI.

Choosing between Cursor and Iterator APIs

It is reasonable to ask at this point, “What API should Ichoose? Should I create instances ofXMLStreamReader orXMLEventReader? Why are there twokinds of APIs anyway?”

Development Goals

The authors of the StAX specification targeted three types of developers:

• Library and infrastructure developers: Need highly efficient, low-level APIs with minimal extensibility requirements.

• J2ME developers: Need small, simple, pull-parsing libraries, and have minimal extensibility needs.

• Java EE and Java SE developers: Need clean, efficient pull-parsing libraries, plus need the flexibility to both read and write XML streams, create new event types, and extend XML document elements and attributes.

Given these wide-ranging development categories, the StAX authors felt it was more usefulto define two small, efficient APIs rather than overloading one larger and necessarilymore complex API.

Comparing Cursor and Iterator APIs

Before choosing between the cursor and iterator APIs, you should note a fewthings that you can do with the iterator API that you cannotdo with cursor API:

• Objects created from theXMLEvent subclasses are immutable, and can be used in arrays, lists, and maps, and can be passed through your applications even after the parser has moved on to subsequent events.

• You can create subtypes ofXMLEvent that are either completely new information items or extensions of existing items but with additional methods.

• You can add and remove events from an XML event stream in much simpler ways than with the cursor API.

Similarly, keep some general recommendations in mind when making your choice:

• If you are programming for a particularly memory-constrained environment, like J2ME, you can make smaller, more efficient code with the cursor API.

• If performance is your highest priority (for example, when creating low-level libraries or infrastructure), the cursor API is more efficient.

• If you want to create XML processing pipelines, use the iterator API.

• If you want to modify the event stream, use the iterator API.

• If you want your application to be able to handle pluggable processing of the event stream, use the iterator API.

• In general, if you do not have a strong preference one way or the other, using the iterator API is recommended because it is more flexible and extensible, thereby “future-proofing” your applications.

Copyright © 2010, Oracle and/or its affiliates. All rights reserved.Legal Notices