Introduction to StAX parser in Java

Introduction to StAX parser in Java

In my earlier post, I gave an introduction to SAX XML parser in Java. In this post we will see an Introduction to StAX parser in Java with example programs. StAX(Streaming API for XML) is a JAVA based API to parse XML documents similar to a SAX parser. There are two main differences between SAX and StAX parsers. They are

  • SAX is a push API. It means that the SAX parser will send(push) notifications to the client program whenever it has processed an element, attribute or character. On the other hand StAX is a pull API.  It means the client application need to ask StAX parser to get information from XML whenever it needs.
  • StAX, is an API for reading and writing XML Documents. SAX can only be used for reading XML.


Note that similar to SAX, StAX can only process the XML document in a linear fashion from top to bottom and you cannot have random access to an XML document .


StAX contains two distinct APIs to work with XML documents. They are

  • Cursor API
  • Event Iterator API


Applications can use any of these two API for parsing XML documents.

Cursor API

As the name suggests, the StAX cursor API represents a cursor with which you can parse 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. The XMLStreamReader interface has methods to read an XML document and the XMLStreamWriter interface provides methods for creating an XML document. Below are some of the important methods defined in XMLStreamReader interface.

  • int next() – used to retrieve next parsing event.
  • boolean hasNext() – Returns true if there are more parsing events and false if there are no more events.
  • String getText() – used to get textcurrent value of an element
  • String getLocalName() – used to get (local)name of an element


The XMLStreamWriter interface has the following important methods.

  • writeStartElement(String localName) – Add start element of given name.
  • writeEndElement(String localName) – Add an end element of given name.
  • writeAttribute(String localName, String value) – Writes an attribute to the output stream without a prefix.
  •  writeCharacters(String text) – Write text to the output.

Read XML using XMLStreamReader

Below is the input XML file we need to parse using XMLStreamReader.

Below is the output of above program.

Create an XML using XMLStreamWriter

We will create the same XML file that we have used in the previous program.

Below is the file created using above program.

StAX parser

Event 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 main parser interface for reading iterator events is XMLEventReader, and the main interface for writing iterator events is XMLEventWriter.

The XMLEventReader interface provide iterator of events which can be used to iterate over events as they occur while parsing the XML document. Following are the important methods defined in the interface.

  • hasNext() – Check if there are more events.
  • nextEvent() – Get the next XMLEvent
  • StartElement asStartElement() – used to retrieve value and attributes of element.
  • EndElement asEndElement() – called at the end of a element.
  • Characters asCharacters() – can be used to obtain characters such a CDATA, whitespace etc.
  • getElementText() – Reads the content of a text-only element.


This XMLEventWriter interface specifies following methods for creating an event.

  • add(Event event) – Add event containing elements to XML.

Read an XML using XMLEventReader

We will use the same input XML file to parse using XMLEventReader.

Below is the output of above program.

Create an XML using XMLEventWriter

We will create the following XML file using XMLEventWriter.

Below is the file created by the above program.

StAX parser in Java

That’s all about parsing and creating XML documents using StAX parser in Java. I hope that this post surely serves as an Introduction to StAX parser in Java. If you have any comments, post it in the comments section.

Additional Resources:

Lesson: Streaming API for XML

Java StAX

The following two tabs change content below.
Working as a Java developer since 2010. Passionate about programming in Java. I am a part time blogger.
One comment

Add Comment

Required fields are marked *. Your email address will not be published.