Java StAX

XML processing is an important weapon in a programmer’s armour. It is not something new and still growing popular by each day. Android embraces it. Every emerging technology incorporates XML. Java supports XML by providing JAXP and it has multiple ways for xml processing and they are SAX, DOM, TrAX, StAX and JAXB.

In this article let us learn about what is StAX API, implementations available and how we can use it. StAX is a streaming pull-parsing java API for reading and writing XMLs and it is an alternate to SAX, DOM and TrAX. StAX API is a set of interfaces providing a framework for bi-directional parser. It provides two sets of APIs, cursor and iterator based.

StAX was carved out of JSR 173.

Important Note: StAX API is set of interfaces only and there is no implementation. There are different implementations available like stax.codehaus, sjsxp, and woodstox. Since there is no implementation with JDK, we need to choose a StAX implementation, download its jar and add it to our classpath to use StAX API for reading and writing XMLs. I am going to use Sun/Oracle’s StAX implementation that comes bundled in Java EE jar (Java EE 6 API Library: javaee-api-6.0.jar). This is available as part of glassfish server or you can download it and use with Eclipse.

SAX, DOM and StAX

SAX is a uni-directional, read only API and follows push model for reading. Read below to know about push reading. SAX and StAX are relatives compared to DOM as DOM uses a completely different approach for XML processing.

DOM parser is created using the concept of trees. XML document object model will be completely constructed as a tree and stored in memory. Then the XML document can be parsed by traversing the tree. This requires lot of memory and processing power. When working with small documents are fine with this kind of DOM processing but when you have a long document and then we will have performance issues.

StAX follows a streaming model, it can both read and write. Imagine feeding a whole XML document via a tube. At every moment one XML element will be the focus and then we move on to the next element either in forward or backward direction of our choice. This is kind of processing is not something new for us, we have seen ResultSet of JDBC API. Streaming has its advantage when we want to process large documents sequentially. Irrespective of size of the document the performance will be good. When mobile phones and apps are getting popular we also need to think of processing in terms of smaller scale compared to desktops and servers.

Example scenario for putting best use of StAX are parsing WSDL in web services, viewing relational database data stored as XML documents and in general parsing predictable document scenarios.

Pull and Push XML Parsing

When processing a XML document there are three parties involved. Party one is XML document, two is the API doing the processing and the final party is the client code which uses the API and gets data from the document.

• Pull: Client => Parser => XML
• Push: Client <= Parser => XML

In pull parsing client code calls the parsing API’s methods to get data and then the parser reads the XML and returns the data required. This is on demand, when client needs it it reads the data.

In push parsing the parser reads the XML document and whenever an event occurs, it pushes the respective data to the client and continues. It is like maintaining a birthday alarm. We register for alarm on a particular date, the alerter keeps running against time and alerts us when it encounters the date.

StAX Cursor API

Cursor API is very similar to JDBC ResultSet in terms of going through the XML. It always moves forward and once in goes past an element, it cannot reach back again. Main interfaces for cursor are XMLStreamReader and XMLStreamWriter and we can see about them below. Cursor API is very similar to SAX as it is unidirectional and it can read properties, shares a light weight memory foot print.

Read XML using XMLStreamReader Cursor

Following code block helps to initialize the factory:

        XMLInputFactory xmlFactory = null;

        try {
            xmlFactory = XMLInputFactory.newInstance();
            xmlFactory.setProperty(
                    XMLInputFactory.IS_REPLACING_ENTITY_REFERENCES,
                    Boolean.TRUE);
            xmlFactory.setProperty(
                    XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES,
                    Boolean.FALSE);
            //IS_COALESCING property to true
			//gets whole text data as one event
            xmlFactory.setProperty(XMLInputFactory.IS_COALESCING, Boolean.FALSE);
        } catch (Exception ex) {
            ex.printStackTrace();
        }

Following lines creates a stream reader.

  XMLStreamReader xmlReader = xmlFactory.createXMLStreamReader(
                    filename,
                    new FileInputStream("zoo.xml"));

Following loops over all the elements available:

  while (xmlReader.hasNext()) {

				//returns the event type
                eventType = xmlReader.next();

				//now print the element by choosing the respective method

				//returns event type for reference
				xmlReader.getEventType();

				//returns the text
				xmlReader.getText();

				//use the right methods for printing attributes, names, etc
             }

Write XML using XMLStreamWriter Cursor

XMLOutputFactory writerFactory =  XMLOutputFactory.newInstance();

XMLStreamWriter xmlWriter = writerFactory.createXMLStreamWriter(new FileWriter("zoo.xml"));

//some example write statements below
xmlWriter.writeComment("comments comments comments");
xmlWriter.writeStartDocument("utf-8","1.0");
xmlWriter.setPrefix("html", "http://www.w3.org/TR/REC-html40");

//startelement followed by text
xmlWriter.writeCharacters("Lion");
xmlWriter.writeEndElement();

StAX Iterator API

Iterator API parses the XML document and returns event objects. These are events for element, text, comment etc. This is similar to the java iterator in collections. Main interfaces in iterator api are XMLEventReader and XMLEventWriter. Base of the iteratore interface is XMLEvent. nextEvent() is the key method which returns the next event in XML stream. This is similar to next in iterator collection. When I say events, we have doubt on exactly what are those events. To clear the doubt following are events types StartDocument, StartElement, EndElement, Characters, EntityReference, ProcessingInstruction, Comment, Attribute, Namespace.

Example Events

<?xml version="1.0"?>
<Zoo xmlns="http://www.animaldept.gov">
    <Lion>
        <Type>Wild</Type>
        <Sound>Roar</Sound>
<!-- it will eat you man -->
    </Lion>
</Zoo>

StartDocument – version 1.0
StartElement – qname = Zoo:http://www.animaldept.gov
Characters – data = Wild

Above three are just example events, every element will have StartElement, EndElement fired.

Read XML using using XMLEventReader Iterator

//create a factory
XMLInputFactory factory = XMLInputFactory.newInstance();

// create xml event reader
XMLEventReader r = factory.createXMLEventReader(filename,
     new FileInputStream(filename));

//create a iterator
while(r.hasNext()) {
    XMLEvent e = r.nextEvent();
    System.out.println(e.toString());
}

Write XML using XMLEventWriter Iterator

// create xml event writer
XMLEventWriter writer =
XMLOutputFactory.newInstance().createXMLEventWriter(
System.out);

//add an event to the writer
writer.add(event);