softwarecave

Streaming API for XML provides interface XMLStreamReader which gives a low-level but very efficient cursor-like API for reading XML documents. When using it we iterate over various events in XML document and extract information about these events. Once we are done with the current event, we move to the next one and continue. The events can be for example the start of element, the end of element or characters data.

Interface XMLStreamReader provides PULL API (compared to SAX which provides PUSH API). It means that the programmer explicitly decides when to extract next event from the XML document and can get prepared to it beforehand. In my opinion PULL interface is more straightforward to use and leads to smaller and more readable code responsible for handling of events.

Well-formedness and validation

XMLStreamReader takes care of most tasks related with parsing of XML documents like expanding entity references, unescaping special characters or handling XML namespaces. It also checks whether XML document is well-formed and raises exception when it is not the case. Unfortunately, it does not validate XML document against XML Schema so it has to be done in some other way.

General XMLStreamReader workflow

To start reading document we have to first create instance of XMLStreamReader using XMLInputFactory:

XMLInputFactory inputFactory = XMLInputFactory.newInstance();
XMLStreamReader reader = inputFactory.createXMLStreamReader(inputStream);

Once we have the reader we can start iterating over events:

while (reader.hasNext()) {
  int eventType = reader.next();
  switch (eventType) {
    case XMLStreamReader.START_ELEMENT:
      // handle start element
    case XMLStreamReader.ATTRIBUTE:
      // handle attribute
    ...
}

Method hasNext checks whether there is still any event to process. If yes, we move to it using next method and we check the type of the event. All possible event types are:

• START_ELEMENT
• ATTRIBUTE
• NAMESPACE
• END_ELEMENT
• CHARACTERS
• CDATA
• COMMENT
• SPACE
• END_DOCUMENT
• PROCESSING_INSTRUCTION
• ENTITY_REFERENCE
• DTD

Depending on the type of the event we can execute different methods of XMLStreamReader interface to retrieve information about the event. For example for START_ELEMENT we can execute getName, getLocalName, hasName, getPrefix, isAttributeSpecified, getElementText and various getAttributeXXX and getNamespaceXXX methods. For event END_ELEMENT the list is less impressive because we cannot access information about attributes and in case of CHARACTERS or CDATA we can only call getTextXXX methods.

When there are no more events to process, we should close the reader to release any resources used by it:

reader.close();

Closing the reader will not close the underlying file or stream so it has to be done manually.

Example

To fully understand the flexibility of this approach let’s look at the simple XML document (which was created in my previous post):

<?xml version="1.0" encoding="UTF-8"?>
<!--Describes list of books-->
<books xmlns="http://example.com/books">
  <book language="English">
    <authors>
      <author>Mark Twain</author>
    </authors>
    <title><![CDATA[The Adventures of Tom Sawyer]]></title>
    <category>FICTION</category>
    <year>1876</year>
  </book>
  <book language="English">
    <authors>
      <author>Niklaus Wirth</author>
    </authors>
    <title><![CDATA[The Programming Language Pascal]]></title>
    <category>PASCAL</category>
    <year>1971</year>
  </book>
  <book language="English">
    <authors>
      <author>O.-J. Dahl</author>
      <author>E. W. Dijkstra</author>
      <author>C. A. R. Hoare</author>
    </authors>
    <title><![CDATA[Structured Programming]]></title>
    <category>PROGRAMMING</category>
    <year>1972</year>
  </book>
</books>

and the code which will try to parse it and will return a list of books:

package com.example.staxread;

import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;

public class BooksReader {

    public List<Book> readFromXML(InputStream is) throws XMLStreamException {
        XMLInputFactory inputFactory = XMLInputFactory.newInstance();
        XMLStreamReader reader = null;
        try {
            reader = inputFactory.createXMLStreamReader(is);
            return readDocument(reader);
        } finally {
            if (reader != null) {
                reader.close();
            }
        }
    }

    private List<Book> readDocument(XMLStreamReader reader) throws XMLStreamException {
        while (reader.hasNext()) {
            int eventType = reader.next();
            switch (eventType) {
                case XMLStreamReader.START_ELEMENT:
                    String elementName = reader.getLocalName();
                    if (elementName.equals("books"))
                        return readBooks(reader);
                    break;
                case XMLStreamReader.END_ELEMENT:
                    break;
            }
        }
        throw new XMLStreamException("Premature end of file");
    }

    private List<Book> readBooks(XMLStreamReader reader) throws XMLStreamException {
        List<Book> books = new ArrayList<>();
        
        while (reader.hasNext()) {
            int eventType = reader.next();
            switch (eventType) {
                case XMLStreamReader.START_ELEMENT:
                    String elementName = reader.getLocalName();
                    if (elementName.equals("book"))
                        books.add(readBook(reader));
                    break;
                case XMLStreamReader.END_ELEMENT:
                    return books;
            }
        }
        throw new XMLStreamException("Premature end of file");
    }

    private Book readBook(XMLStreamReader reader) throws XMLStreamException {
        Book book = new Book("", "", null, "", 0);
        book.setLanguage(reader.getAttributeValue(null, "language"));
        
        while (reader.hasNext()) {
            int eventType = reader.next();
            switch (eventType) {
                case XMLStreamReader.START_ELEMENT:
                    String elementName = reader.getLocalName();
                    if (elementName.equals("authors"))
                        book.setAuthors(readAuthors(reader));
                    else if (elementName.equals("title"))
                        book.setTitle(readCharacters(reader));
                    else if (elementName.equals("category"))
                        book.setCategory(readCategory(reader));
                    else if (elementName.equals("year"))
                        book.setYear(readInt(reader));
                    break;
                case XMLStreamReader.END_ELEMENT:
                    return book;
            }
        }
        throw new XMLStreamException("Premature end of file");
    }

    private List<String> readAuthors(XMLStreamReader reader) throws XMLStreamException {
        List<String> authors = new ArrayList<>();
        while (reader.hasNext()) {
            int eventType = reader.next();
            switch (eventType) {
                case XMLStreamReader.START_ELEMENT:
                    String elementName = reader.getLocalName();
                    if (elementName.equals("author"))
                        authors.add(readCharacters(reader));
                    break;
                case XMLStreamReader.END_ELEMENT:
                    return authors;
            }
        }
        throw new XMLStreamException("Premature end of file");

    }
    
    private String readCharacters(XMLStreamReader reader) throws XMLStreamException {
        StringBuilder result = new StringBuilder();
        while (reader.hasNext()) {
            int eventType = reader.next();
            switch (eventType) {
                case XMLStreamReader.CHARACTERS:
                case XMLStreamReader.CDATA:
                    result.append(reader.getText());
                    break;
                case XMLStreamReader.END_ELEMENT:
                    return result.toString();
            }
        }
        throw new XMLStreamException("Premature end of file");
    }
    
    private Category readCategory(XMLStreamReader reader) throws XMLStreamException {
        String characters = readCharacters(reader);
        try {
            return Category.valueOf(characters);
        } catch(IllegalArgumentException e) {
            throw new XMLStreamException("Invalid category " + characters);
        }
    }
    
    private int readInt(XMLStreamReader reader) throws XMLStreamException {
        String characters = readCharacters(reader);
        try {
            return Integer.valueOf(characters);
        } catch (NumberFormatException e) {
            throw new XMLStreamException("Invalid integer " + characters);
        }
    }
}

The most important thing is that we create several methods for reading various XML elements and we call one method from another depending on the name of the element which has just started. It clearly resembles the hierarchical structure of XML documents.

When we are reading a book in readBook method we also extract attribute language before we start iterating over events. Of course, we could iterate over events and appropriately handle ATTRIBUTE event but this approach was much easier.

Additionally, the parser can emit several CHARACTERS or CDATA events in a row so we have to concatenate their text in readCharacters method. It is possible to force the parser to emit only one such event with concatenated text by setting javax.xml.stream.isCoalescing property on XMLInputFactory before instantiating the reader. The factory also supports several other properties which you may find useful.

Conclusion

Streaming API for XML provides very good but still low-level parser for reading XML documents. This is perfect when you want to have great control over parsing or want to process only few parts of the XML document. Additionally, it is much easier to use than SAX parser and does not require building DOM tree but instead it is possible to read data directly into your own data structures.

The source code for this example you can find at GitHub.

Nowadays XML became a de-facto standard for storing and exchanging documents over Internet. And because it was designed to be extensible, it can be easily adapted to almost every need. In this post I would like to describe how to create and write your own XML documents using Streaming API for XML (StAX).

Need for XML writer

Of course it is possible to write XML documents using a combination of print, println or printf methods but the amount of work and the number of details to take care of would be quite large. For example when writing documents manually it is very easy to forget about escaping special characters like < or " or prepending tag with namespace prefix. Therefore, it is better to leave these cumbersome tasks to the XML writer and concentrate on the general document layout.

XMLStreamWriter

Streaming API for XML introduced in Java 6 provides quite handy interface XMLStreamWriter which can be used for writing XML files. The good thing about this API is that it does not require building any specific object structure like in DOM and does not require doing any intermediate tasks.

Additionally, XMLStreamWriter supports namespaces by default which is very useful in more advanced situations.

General XMLStreamWriter workflow

To start writing document we have to create instance of XMLStreamWriter using XMLOutputFactory:

XMLOutputFactory outputFactory = XMLOutputFactory.newFactory();
XMLStreamWriter writer = outputFactory.createXMLStreamWriter(outputStream);

Once we have the instance of XMLStreamWriter we must write header of the XML document:

writer.writeStartDocument("utf-8", "1.0");

Then we can proceed to writing elements:

writer.writeStartElement("books");

Once we have element started we can add attributes to it, write some character data or CDATA section:

writer.writeAttribute("id", "10");
writer.writeCharacters("text data");
writer.writeCData("more text data");

We can also start some other nested elements and so on.

To close opened elements we should call:

writer.writeEndElement();

It is also possible to write empty elements:

writer.writeEmptyElement("used & new");

or write comments:

writer.writeComment("Some comment");

When we are done with writing, we should finish the document and close the writer:

writer.writeEndDocument();
writer.close();

which will automatically close all opened elements and will release resources used by the writer.

Closing the writer will not close the underlying file so it has to be done manually.

Issues with XMLStreamWriter

XMLStreamWriter is not perfect so it is still possible to create not well-formed XML documents which for example contain more than one root element or miss namespace definition.

Additionally, XMLStreamWriter does not indent its output so it may be a bit hard to read using plain text editor. Therefore, for reading I suggest to open it in a web browser most of which have user-friendly interface to view structure of XML documents.

Writing XML document without namespaces

Below I would like to show a simple example how to write your own data structure into XML document. In our case it will be a list of books and a single book will be represented like this:

package com.example.staxwrite;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

public class Book {
    private List<String> authors;
    private String title;
    private Category category;
    private String language;
    private int year;

    public Book(List<String> authors, String title, Category category, String language, int year) {
        this.authors = new ArrayList<>(authors);
        this.title = title;
        this.category = category;
        this.language = language;
        this.year = year;
    }

    public Book(String author, String title, Category category, String language, int year) {
        this (Collections.singletonList(author), title, category, language, year);
    }

    public List<String> getAuthors() {
        return Collections.unmodifiableList(authors);
    }

    public void addAuthor(String author) {
        authors.add(author);
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public Category getCategory() {
        return category;
    }

    public void setCategory(Category category) {
        this.category = category;
    }

    public String getLanguage() {
        return language;
    }

    public void setLanguage(String language) {
        this.language = language;
    }

    public int getYear() {
        return year;
    }

    public void setYear(int year) {
        this.year = year;
    }
    
}

The code which handles writing XML document is following:

package com.example.staxwrite;

import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;

public class NoNSWriter {

    public void writeToXml(Path path, List<Book> books) throws IOException, XMLStreamException {
        try (OutputStream os = Files.newOutputStream(path)) {
            XMLOutputFactory outputFactory = XMLOutputFactory.newFactory();
            XMLStreamWriter writer = null;
            try {
                writer = outputFactory.createXMLStreamWriter(os, "utf-8");
                writeBooksElem(writer, books);
            } finally {
                if (writer != null)
                    writer.close();
            }
        }
    }

    private void writeBooksElem(XMLStreamWriter writer, List<Book> books) throws XMLStreamException {
        writer.writeStartDocument("utf-8", "1.0");
        writer.writeComment("Describes list of books");
        
        writer.writeStartElement("books");
        for (Book book : books)
            writeBookElem(writer, book);
        writer.writeEndElement();

        writer.writeEndDocument();
    }

    private void writeBookElem(XMLStreamWriter writer, Book book) throws XMLStreamException {
        writer.writeStartElement("book");
        writer.writeAttribute("language", book.getLanguage());

        writeAuthorsElem(writer, book.getAuthors());

        writer.writeStartElement("title");
        writer.writeCData(book.getTitle());
        writer.writeEndElement();

        writer.writeStartElement("category");
        writer.writeCharacters(book.getCategory().name());
        writer.writeEndElement();

        writer.writeStartElement("year");
        writer.writeCharacters(Integer.toString(book.getYear()));
        writer.writeEndElement();

        writer.writeEndElement();
    }

    private void writeAuthorsElem(XMLStreamWriter writer, List<String> authors) throws XMLStreamException {
        writer.writeStartElement("authors");
        for (String author : authors) {
            writer.writeStartElement("author");
            writer.writeCharacters(author);
            writer.writeEndElement();
        }
        writer.writeEndElement();
    }
}

In writeToXml method we create the output stream and the writer and ensure that they will be closed properly. Then we call writeBooksElem which will start the document, write comment, emit the list of books and will finish the document.

Most properties of a book are written as separate subelements except language which is written as an attribute. The resultant XML document should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!--Describes list of books-->
<books>
  <book language="English">
    <authors>
      <author>Mark Twain</author>
    </authors>
    <title><![CDATA[The Adventures of Tom Sawyer]]></title>
    <category>FICTION</category>
    <year>1876</year>
  </book>
  <book language="English">
    <authors>
      <author>Niklaus Wirth</author>
    </authors>
    <title><![CDATA[The Programming Language Pascal]]></title>
    <category>PASCAL</category>
    <year>1971</year>
  </book>
  <book language="English">
    <authors>
      <author>O.-J. Dahl</author>
      <author>E. W. Dijkstra</author>
      <author>C. A. R. Hoare</author>
    </authors>
    <title><![CDATA[The Programming Language Pascal]]></title>
    <category>PROGRAMMING</category>
    <year>1972</year>
  </book>
</books>

Writing XML document with namespaces

The XML document created using code above does not contain any references to namespaces. While it may be convenient in simple cases, more advanced XML documents will refer to one or more XML namespaces.

To create document with namespace support we have to first define the prefix of the namespace we want to use:

writer.setPrefix("b", "http://example.com/books");

and emit the element with URI of this namespace:

writer.writeStartElement("http://example.com/books", "books");
writer.writeNamespace("b", "http://example.com/books");

Once we do so, we can write elements and attributes from this namespace by adding the namepace URI as the first argument of writeStartElement and writeAttribute methods. Here is the full code:

package com.example.staxwrite;

import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;

public class NSWriter {

    private static final String NS = "http://example.com/books";
    
    public void writeToXml(Path path, List<Book> books) throws IOException, XMLStreamException {
        try (OutputStream os = Files.newOutputStream(path)) {
            XMLOutputFactory outputFactory = XMLOutputFactory.newFactory();
            XMLStreamWriter writer = null;
            try {
                writer = outputFactory.createXMLStreamWriter(os, "utf-8");
                writeBooksElem(writer, books);
            } finally {
                if (writer != null)
                    writer.close();
            }
        }
    }

    private void writeBooksElem(XMLStreamWriter writer, List<Book> books) throws XMLStreamException {
        writer.writeStartDocument("utf-8", "1.0");
        writer.writeComment("Describes list of books");
        
        writer.setPrefix("b", NS);
        writer.writeStartElement(NS, "books");
        writer.writeNamespace("b", NS);
        for (Book book : books)
            writeBookElem(writer, book);
        writer.writeEndElement();

        writer.writeEndDocument();
    }

    private void writeBookElem(XMLStreamWriter writer, Book book) throws XMLStreamException {
        writer.writeStartElement(NS, "book");
        writer.writeAttribute(NS, "language", book.getLanguage());

        writeAuthorsElem(writer, book.getAuthors());

        writer.writeStartElement(NS, "title");
        writer.writeCData(book.getTitle());
        writer.writeEndElement();

        writer.writeStartElement(NS, "category");
        writer.writeCharacters(book.getCategory().name());
        writer.writeEndElement();

        writer.writeStartElement(NS, "year");
        writer.writeCharacters(Integer.toString(book.getYear()));
        writer.writeEndElement();

        writer.writeEndElement();
    }

    private void writeAuthorsElem(XMLStreamWriter writer, List<String> authors) throws XMLStreamException {
        writer.writeStartElement(NS, "authors");
        for (String author : authors) {
            writer.writeStartElement(NS, "author");
            writer.writeCharacters(author);
            writer.writeEndElement();
        }
        writer.writeEndElement();
    }
}

and the created XML document:

<?xml version="1.0" encoding="UTF-8"?>
<!--Describes list of books-->
<b:books xmlns:b="http://example.com/books">
  <b:book b:language="English">
    <b:authors>
      <b:author>Mark Twain</b:author>
    </b:authors>
    <b:title><![CDATA[The Adventures of Tom Sawyer]]></b:title>
    <b:category>FICTION</b:category>
    <b:year>1876</b:year>
  </b:book>
  <b:book b:language="English">
    <b:authors>
      <b:author>Niklaus Wirth</b:author>
    </b:authors>
    <b:title><![CDATA[The Programming Language Pascal]]></b:title>
    <b:category>PASCAL</b:category>
    <b:year>1971</b:year>
  </b:book>
  <b:book b:language="English">
    <b:authors>
      <b:author>O.-J. Dahl</b:author>
      <b:author>E. W. Dijkstra</b:author>
      <b:author>C. A. R. Hoare</b:author>
    </b:authors>
    <b:title><![CDATA[The Programming Language Pascal]]></b:title>
    <b:category>PROGRAMMING</b:category>
    <b:year>1972</b:year>
  </b:book>
</b:books>

Write XML document with default namespace

XML also supports the idea of default namespace which increases readability and limits the typing. Using it is very similar to using namespace with explicit prefix but we have to use setDefaultNamespace and writeDefaultNamespace instead of setPrefix and writeNamespace:

package com.example.staxwrite;

import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;

public class DefaultNSWriter {

    private static final String NS = "http://example.com/books";
    
    public void writeToXml(Path path, List<Book> books) throws IOException, XMLStreamException {
        try (OutputStream os = Files.newOutputStream(path)) {
            XMLOutputFactory outputFactory = XMLOutputFactory.newFactory();
            XMLStreamWriter writer = null;
            try {
                writer = outputFactory.createXMLStreamWriter(os, "utf-8");
                writeBooksElem(writer, books);
            } finally {
                if (writer != null)
                    writer.close();
            }
        }
    }

    private void writeBooksElem(XMLStreamWriter writer, List<Book> books) throws XMLStreamException {
        writer.writeStartDocument("utf-8", "1.0");
        writer.writeComment("Describes list of books");
        
        writer.setDefaultNamespace(NS);
        writer.writeStartElement(NS, "books");
        writer.writeDefaultNamespace(NS);
        for (Book book : books)
            writeBookElem(writer, book);
        writer.writeEndElement();

        writer.writeEndDocument();
    }

    private void writeBookElem(XMLStreamWriter writer, Book book) throws XMLStreamException {
        writer.writeStartElement(NS, "book");
        writer.writeAttribute(NS, "language", book.getLanguage());

        writeAuthorsElem(writer, book.getAuthors());

        writer.writeStartElement(NS, "title");
        writer.writeCData(book.getTitle());
        writer.writeEndElement();

        writer.writeStartElement(NS, "category");
        writer.writeCharacters(book.getCategory().name());
        writer.writeEndElement();

        writer.writeStartElement(NS, "year");
        writer.writeCharacters(Integer.toString(book.getYear()));
        writer.writeEndElement();

        writer.writeEndElement();
    }

    private void writeAuthorsElem(XMLStreamWriter writer, List<String> authors) throws XMLStreamException {
        writer.writeStartElement(NS, "authors");
        for (String author : authors) {
            writer.writeStartElement(NS, "author");
            writer.writeCharacters(author);
            writer.writeEndElement();
        }
        writer.writeEndElement();
    }
}

The created XML document refers to the namespace but there is no prefix used:

<?xml version="1.0" encoding="UTF-8"?>
<!--Describes list of books-->
<books xmlns="http://example.com/books">
  <book language="English">
    <authors>
      <author>Mark Twain</author>
    </authors>
    <title><![CDATA[The Adventures of Tom Sawyer]]></title>
    <category>FICTION</category>
    <year>1876</year>
  </book>
  <book language="English">
    <authors>
      <author>Niklaus Wirth</author>
    </authors>
    <title><![CDATA[The Programming Language Pascal]]></title>
    <category>PASCAL</category>
    <year>1971</year>
  </book>
  <book language="English">
    <authors>
      <author>O.-J. Dahl</author>
      <author>E. W. Dijkstra</author>
      <author>C. A. R. Hoare</author>
    </authors>
    <title><![CDATA[The Programming Language Pascal]]></title>
    <category>PROGRAMMING</category>
    <year>1972</year>
  </book>
</books>

Conclusion

Streaming API for XML provides very convenient, fast and memory efficient way to write XML documents without worrying about details and escaping of special characters. It is a great alternative to DOM especially when you don’t need to keep and manage DOM tree in memory for any reason.

The source code for example is available at GitHub.