java-xmlbuilder

XML Builder is a utility that allows simple XML documents to be constructed
using relatively sparse Java code.

It allows for quick and painless creation of XML documents where you might
otherwise be tempted to use concatenated strings, and where you would rather
not face the tedium and verbosity of coding with
JAXP.

Internally, XML Builder uses JAXP to build a standard W3C Document model (DOM)
that you can easily export as a string, or access directly to manipulate
further if you have special requirements.

License

Apache License Version 2.0

XMLBuilder versus XMLBuilder2

Since version 1.1 this library provides two builder implementations and APIs:

• XMLBuilder – the original API – follows standard Java practice of
  re-throwing lower level checked exceptions when you do things like create a
  new document.
  You must explicitly catch these checked exceptions in your codebase, even
  though they are unlikely to occur in tested code.
• XMLBuilder2 is a newer API that removes checked exceptions altogether, and
  will instead wrap and propagate lower level exceptions in an unchecked
  XMLBuilderRuntimeException.
  Use this class if you don’t like the code mess or overhead of try/catching
  many low-level exceptions that are unlikely to occur in practice.

Both these versions work identically apart from the handling of errors, so you
can use whichever version you prefer or “upgrade” from one to the other in
existing code.

Quick Example

Easily build XML documents using code structured like the final document.

This code:

XMLBuilder2 builder = XMLBuilder2.create("Projects")
    .e("java-xmlbuilder").a("language", "Java").a("scm","SVN")
        .e("Location").a("type", "URL")
            .t("http://code.google.com/p/java-xmlbuilder/")
        .up()
    .up()
    .e("JetS3t").a("language", "Java").a("scm","CVS")
        .e("Location").a("type", "URL")
            .t("http://jets3t.s3.amazonaws.com/index.html");

Produces this XML document:

<?xml version="1.0" encoding="UTF-8"?>
<Projects>
    <java-xmlbuilder language="Java" scm="SVN">
        <Location type="URL">http://code.google.com/p/java-xmlbuilder/</Location>
    </java-xmlbuilder>
    <JetS3t language="Java" scm="CVS">
        <Location type="URL">http://jets3t.s3.amazonaws.com/index.html</Location>
    </JetS3t>
</Projects>

Getting Started

See further example usage below and in the
JavaDoc documentation.

Download a Jar file containing the latest version
java-xmlbuilder-1.3.jar.

Maven users can add this project as a dependency with the following additions
to a POM.xml file:

<dependencies>
  . . .
  <dependency>
    <groupId>com.jamesmurty.utils</groupId>
    <artifactId>java-xmlbuilder</artifactId>
    <version>1.3</version>
  </dependency>
  . . .
</dependencies>

How to use the XMLBuilder

Read below for examples that show how you would use the XMLBuilder utility to
create and manipulate XML documents like the following:

<?xml version="1.0" encoding="UTF-8"?>
<Projects>
    <java-xmlbuilder language="Java" scm="SVN">
        <Location type="URL">http://code.google.com/p/java-xmlbuilder/</Location>
    </java-xmlbuilder>
    <JetS3t language="Java" scm="CVS">
        <Location type="URL">http://jets3t.s3.amazonaws.com/index.html</Location>
    </JetS3t>
</Projects>

Create a New XML Document

To begin, you create a new builder and XML document by specifying the name of
the document’s root element. See the parsing methods below if you want to start
with an existing XML document.

XMLBuilder builder = XMLBuilder.create("Projects");

The XMLBuilder object returned by the create method, and by all other XML
manipulation methods, provides methods that you can use to add more nodes to
the document. For example, to add the java-xmlbuilder and JetS3t nodes to
the root element you could do the following.

XMLBuilder e1 = builder.element("java-xmlbuilder");
XMLBuilder e2 = builder.element("JetS3t");

And to add attributes or further sub-elements to the two new elements, you
could call the appropriate methods on the variables assigned to each new node
like so:

e1.attribute("language", "Java");
e1.attribute("scm", "SVN");

This is straight-forward enough, but it is far more verbose than necessary
because the code does not take advantage of XMLBuilder’s method-chaining
feature.

Method Chaining

Every XMLBuilder method that adds something to the XML document will return an
XMLBuilder object that represents either a newly-added element, or the element
to which something has been added. This feature means that you can chain
together many method calls without the need to assign intermediate objects to
variables.

With this in mind, here is code that performs the same job as the code above
without any unnecessary variables.

XMLBuilder builder = XMLBuilder.create("Projects")
    .element("java-xmlbuilder")
        .attribute("language", "Java")
        .attribute("scm", "SVN")
        .element("Location")
        .up()
    .up()
    .element("JetS3t");

There are two important things to notice in the code above:

• When you add a new element to the document with the element method, the
  XMLBuilder node returned will represent that new element. If you invoke
  methods on this node, attributes and elements will be added to the new node
  rather than to the document’s root.
• Once you have finished adding items to a new element, you can call the
  up() method to retrieve the XMLBuilder node that represents the parent of
  the current node. If you balance every call to element() with a call to
  up(), you can write code that closely resembles the structure of the XML
  document you are creating.

Shorthand Methods

To make your XML building code even shorter and easier to type, there are
shorthand synonyms for every XML manipulation method. Instead of calling
element() you can use the elem() or e() methods, and instead of typing
attribute() you can use attr() or a().

Here is the complete code to build our example XML document using shorthand
methods.

XMLBuilder builder = XMLBuilder.create("Projects")
    .e("java-xmlbuilder")
        .a("language", "Java")
        .a("scm","SVN")
        .e("Location")
            .a("type", "URL")
            .t("http://code.google.com/p/java-xmlbuilder/")
        .up()
    .up()
    .e("JetS3t")
        .a("language", "Java")
        .a("scm","CVS")
        .e("Location")
            .a("type", "URL")
            .t("http://jets3t.s3.amazonaws.com/index.html");

The following methods are available for adding items to the XML document:

Output

XMLBuilder includes two convenient methods for outputting a document.

You can use the toWriter method to print the document to an output stream or
file:

PrintWriter writer = new PrintWriter(new FileOutputStream("projects.xml"));
builder.toWriter(writer, outputProperties);

Or you can convert the document straight to a text string:

builder.asString(outputProperties);

Both of these output methods take an outputProperties parameter that you can
use to control how the output is generated. Any output properties you provide
are forwarded to the underlying Transformer object that is used to serialize
the XML document.

You might specify any non-standard properties like so:

Properties outputProperties = new Properties();
// Explicitly identify the output as an XML document
outputProperties.put(javax.xml.transform.OutputKeys.METHOD, "xml");
// Pretty-print the XML output (doesn't work in all cases)
outputProperties.put(javax.xml.transform.OutputKeys.INDENT, "yes");
// Get 2-space indenting when using the Apache transformer
outputProperties.put("{http://xml.apache.org/xslt}indent-amount", "2");
// Omit the XML declaration header
outputProperties.put(
    javax.xml.transform.OutputKeys.OMIT_XML_DECLARATION, "yes");

If you do not wish to change the default properties for your output, you can
provide a null value for outputProperties.

Accessing the Underlying Document

Because XMLBuilder merely acts as a layer on top of the standard JAXP XML
document building tools, you can easily access the underlying Element or
Document objects if you need to manipulate them in ways that XMLBuilder does
not allow.

To obtain the Element represented by any given XMLBuilder node:

org.w3c.dom.Element element = xmlBuilderNode.getElement();

To obtain the entire XML document:

org.w3c.dom.Document doc = builder.getDocument();

You can also use the root() method to quickly obtain the builder object that
represents the document’s root element, no matter deep an element hierarchy
your code has built:

org.w3c.dom.Element rootElement =
    XMLBuilder.create("This")
        .e("Element")
            .e("Hierarchy")
                .e("Is")
                    .e("Really")
                        .e("Very")
                            .e("Deep")
                                .e("Indeed")
    .root().getElement();

Parse XML

If you already have an XML document to which you need to add nodes or
attributes, you can create a new XMLBuilder instance by parsing an
InputSource, String, or File:

XMLBuilder builder = XMLBuilder.parse(YOUR_XML_DOCUMENT_STRING);

Parsing an existing document will produce an XMLBuilder object pointing at the
document’s root Element node. If you add elements or attributes to this builder
object, they will be added to the document’s root element.

If you need to add nodes elsewhere in the parsed document, you will need to
find the correct location in the document using XPath statements.

Find Nodes with XPath

To add nodes at a specific point in an XML document, you can use XPath to
obtain an XMLBuilder at the correct location. The XMLBuilder#xpathFind method
takes an XPath query string and returns a builder object located at the first
Element that matches the query.

XMLBuilder firstLocationBuilder = builder.xpathFind("//Location");

Note that the XPath query provided to this method must resolve to at least one
Element node. If the query does not match any nodes, or if the first match is
anything other than an Element, the method will throw an
XPathExpressionException.

Like all other XMLBuilder methods, this method can be easily chained to others
when adding nodes. Here is an example that adds a second element, Location2,
inside the JetS3t element of our example document.

builder.xpathFind("//JetS3t").elem("Location2").attr("type", "Testing");

To produce:

<Projects>
  <java-xmlbuilder language="Java" scm="SVN">
    <Location type="URL">http://code.google.com/p/java-xmlbuilder/</Location>
  </java-xmlbuilder>
  <JetS3t language="Java" scm="CVS">
    <Location type="URL">http://jets3t.s3.amazonaws.com/index.html</Location>
    <Location2 type="Testing"></Location2>
  </JetS3t>
</Projects>

Configuring advanced features

When creating or parsing a document you can enable and disable advanced
features by using the more explicit versions of the parse() and create()
constructors.

You can:

• use the enableExternalEntities flag to enable or disable external entities.
  NOTE: you should leave these disabled, as they are by default, unless you
  really need them because they open you to XML External Entity (XXE) injection
  attacks.
• use the isNamespaceAware flag to enable or disable namespace awareness in
  the underlying DocumentBuilderFactory.

Release History

See this project’s version history in
CHANGES.md

This project was previously hosted on Google Code at
https://code.google.com/p/java-xmlbuilder/.
Please refer to this old location for historical issue reports and user
questions.