Write an org.w3.dom.Document to a File

1. Overview

An important part of XML handling is creating XML files that can be consumed by others.

When handling XML in Java, we’ll often have an instance of org.w3c.dom.Document that we need to export.

In this quick tutorial, we’ll see how to write a Document to a file both in an in-line as well as a pretty-printed format.

2. Using a Transformer

The heavy-lifter when writing Documents to files is javax.xml.transform.Transformer.

2.1. Creating the Transformer

So, let’s start by getting a TransformerFactory. We’ll use this factory to create the transformer:

TransformerFactory transformerFactory = TransformerFactory.newInstance()

The system property javax.xml.transform.TransformerFactory specifies which factory implementation to create. Consequently, this property names a concrete subclass of the TransformerFactory abstract class. But, if we don’t define this property, the transformer will simply use a platform default.

Note that since Java 9, we can use TransformerFactory.newDefaultInstance() to create the built-in system-default implementation.

Now that we have the factory, let’s create the Transformer:

Transformer transformer = transformerFactory.newTransformer();

2.2. Specifying the Source and Result

The Transformer transforms a source into a result. In our case, the source is the XML document and the result is the output file.

First, let’s specify the source of the transformation. Here, we’ll use our Document to construct a DOM source:

DOMSource source = new DOMSource(document);

Note that the source doesn’t have to be the whole document. So long as the XML is well-formed, we can use a sub-tree of the document.

Next, we’ll specify where the transformer should write the result of the transformation:

FileWriter writer = new FileWriter(new File(fileName));
StreamResult result = new StreamResult(writer);

Here, we’re telling the transformer that the result is a file stream. But, we can use any kind of java.io.Writer or java.io.OutputStream to create the StreamResult. For example, we could use a StringWriter to construct a String that can then be logged.

2.3. Creating the XML File

Finally, we’ll tell the transformer to operate on the source object and output to the result object:

transformer.transform(source, result);

This will finally create a file with the contents of the XML document:

<?xml version="1.0" encoding="UTF-8" standalone="no"?><Company><Department name="Sales">
  <Employee name="John Smith"/><Employee name="Tim Dellor"/></Department></Company>

3. Customizing the Output

We can customize the XML written to the file by specifying a variety of output properties. Let’s explore a few of these.

3.1. Pretty-Printing the Output

Now, our default transformer simply wrote everything onto a single line, which isn’t as pleasant to read. Indeed, it would be even more difficult to read if the XML were large.

We can configure our transformer for pretty-printing by setting the OutputKeys.INDENT property on the transformer:

transformer.setOutputProperty(OutputKeys.INDENT, "yes");
transformer.setOutputProperty("{http://xml.apache.org/xslt}indent-amount", "4");

Notice that along with the OutputKeys.INDENT, we have also specified the indent-amount property here. This will indent the output correctly, as by default the indentation is zero spaces.

With the above properties set, we get a much nicer output:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Company>
    <Department name="Sales">
        <Employee name="John Smith"/>
        <Employee name="Tim Dellor"/>
    </Department>
</Company>

3.2. Omitting the XML Declaration

Sometimes, we might want to exclude the XML declaration.

We can configure our transformer to do this by setting the OutputKeys.OMIT_XML_DECLARATION property:

transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");

And using our transformer again, we get:

<Company>
    <Department name="Sales">
        <Employee name="John Smith"/>
        <Employee name="Tim Dellor"/>
    </Department>
</Company>

3.3. Other Output Properties

So, apart from pretty-printing and omitting the XML declaration, we can customize the output in other ways, too:

• We can specify the XML version using OutputKeys.VERSION, the default is “1.0”
• We can indicate our preferred character encoding using OutputKeys.ENCODING, the default is “utf-8”
• And, we can also specify other typical declaration attributes like SYSTEM, PUBLIC, and STANDALONE.

4. Conclusion

In this tutorial, we saw how to export an org.w3c.Document to a file and how to customize the output.

And, of course, the accompanying source code is available over on GitHub.