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:

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:

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:

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:

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:

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.