Package org.dom4j

Defines the XML Document Object Model in Java interfaces together with some helper classes.

See:
Description

Interface Summary

Attribute	Attribute defines an XML attribute.
Branch	Branch interface defines the common behaviour for Nodes which can contain child nodes (content) such as XML elements and documents.
CDATA	CDATA defines an XML CDATA section.
CharacterData	CharacterData is a marker interface for character based nodes such as the CDATA,Comment and Text nodes.
Comment	Comment defines the behavior of an XML comment.
Document	Document defines an XML Document.
DocumentType	DocumentType defines an XML DOCTYPE declaration.
Element	Element interface defines an XML element.
ElementHandler	ElementHandler interface defines a handler of Element objects.
ElementPath	This interface is used by ElementHandlerinstances to retrieve information about the current path hierarchy they are to process.
Entity	Entity defines an XML entity.
Node	Node defines the polymorphic behavior for all XML nodes in a dom4j tree.
NodeFilter	NodeFilter defines the behavior for a filter or predicate which acts on a DOM4J Node.
ProcessingInstruction	ProcessingInstruction defines an XML processing instruction.
Text	Text defines an XML Text node.
Visitor	Visitor is used to implement the Visitor pattern in DOM4J.
XPath	XPath represents an XPath expression after it has been parsed from a String.

Class Summary

DocumentFactory	DocumentFactory is a collection of factory methods to allow easy custom building of DOM4J trees.
DocumentHelper	DocumentHelper is a collection of helper methods for using DOM4J.
Namespace	Namespace is a Flyweight Namespace that can be shared amongst nodes.
QName	QName represents a qualified name value of an XML element or attribute.
VisitorSupport	VisitorSupport is an abstract base class which is useful for implementation inheritence or when using anonymous inner classes to create simple Visitor implementations.

Exception Summary

DocumentException	DocumentException is a nested Exception which may be thrown during the processing of a DOM4J document.
IllegalAddException	IllegalAddException is thrown when a node is added incorrectly to an Element
InvalidXPathException	InvalidXPathException is thrown when an invalid XPath expression is used to traverse an XML document
XPathException	XPathException is thrown when an exception occurs while evaluating an XPath expression, usually due to some function throwing an exception.

Package org.dom4j Description

Defines the XML Document Object Model in Java interfaces together with some helper classes.

Quick Start

→ see also http://www.dom4j.org

Parsing XML

One of the first things you'll probably want to do is to parse an XML document of some kind. This is easy to do in dom4j. The following code demonstrates how to this.

import java.net.URL;

import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.dom4j.io.SAXReader;

public class Foo {

    public Document parse(URL url) throws DocumentException {
        SAXReader reader = new SAXReader();
        Document document = reader.read(url);
        return document;
    }
}

Looping over elements and attributes

A document can be navigated using a variety of methods that return standard Java Collections or Iterators. For example

    public void bar(Document document) throws DocumentException {

        Element root = document.getRootElement();

        // iterate through child elements of root
        for ( Element element : root.elements() ) {
            // do something 
        }

        // iterate through child elements of root with element name "foo"
        for ( Element element : root.elements("foo") ) {
            // do something
        }

        // iterate through attributes of root 
        for ( Attribute attribute : root.attributes() ) {
            // do something
        }
     }

Powerful Navigation with XPath

In dom4j XPath expressions can be evaluated on the Document or on any Node in the tree (such as Attribute, Element or ProcessingInstruction). This allows complex navigation throughout the document with a single line of code. For example.

    public void bar(Document document) {
        List list = document.selectNodes( "//foo/bar" );

        Node node = document.selectSingleNode( "//foo/bar/author" );

        String name = node.valueOf( "@name" );
    }

For example if you wish to find all the hypertext links in an XHTML document the following code would do the trick.

    public void findLinks(Document document) throws DocumentException {

        List list = document.selectNodes( "//a/@href" );

        for ( Node node : list ) {
            Attribute attribute = (Attribute)node;
            String url = attribute.getValue();
        }
    }

If you need any help learning the XPath language we highly recommend the Zvon tutorial which allows you to learn by example.

Looping with index

You can also use the standard for-loop construct with indices:

    public void treeWalk(Document document) {
        treeWalk( document.getRootElement() );
    }

    public void treeWalk(Element element) {
        for ( int i = 0, size = element.nodeCount(); i < size; i++ ) {
            Node node = element.node(i);
            if ( node instanceof Element ) {
                treeWalk( (Element) node );
            }
            else {
                // do something....
            }
        }
    }

Creating a new XML document

Often in dom4j you will need to create a new document from scratch. Here's an example of doing that.

import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;

public class Foo {

    public Document createDocument() {
        Document document = DocumentHelper.createDocument();
        Element root = document.addElement( "root" );

        Element author1 = root.addElement( "author" )
            .addAttribute( "name", "James" )
            .addAttribute( "location", "UK" )
            .addText( "James Strachan" );
        
        Element author2 = root.addElement( "author" )
            .addAttribute( "name", "Bob" )
            .addAttribute( "location", "US" )
            .addText( "Bob McWhirter" );

        return document;
    }
}

Writing a document to a file

A quick and easy way to write a Document (or any Node) to a Writer is via the write() method.

    FileWriter out = new FileWriter( "foo.xml" );
    document.write( out );

If you want to be able to change the format of the output, such as pretty printing or a compact format, or you want to be able to work with Writer objects or OutputStream objects as the destination, then you can use the XMLWriter class.

import org.dom4j.Document;
import org.dom4j.io.OutputFormat;
import org.dom4j.io.XMLWriter;

public class Foo {

    public void write(Document document) throws IOException {

        // lets write to a file
        XMLWriter writer = new XMLWriter(
            new FileWriter( "output.xml" )
        );
        writer.write( document );
        writer.close();


        // Pretty print the document to System.out
        OutputFormat format = OutputFormat.createPrettyPrint();
        writer = new XMLWriter( System.out, format );
        writer.write( document );

        // Compact format to System.out
        format = OutputFormat.createCompactFormat();
        writer = new XMLWriter( System.out, format );
        writer.write( document );
    }
}

Converting to and from Strings

If you have a reference to a Document or any other Node such as an Attribute or Element, you can turn it into the default XML text via the asXML() method.

        Document document = ...;
        String text = document.asXML();

If you have some XML as a String you can parse it back into a Document again using the helper method DocumentHelper.parseText()

        String text = "<person> <name>James</name> </person>";
        Document document = DocumentHelper.parseText(text);

Styling a Document with XSLT

Applying XSLT on a Document is quite straightforward using the JAXP API from Sun. This allows you to work against any XSLT engine such as Xalan or SAXON. Here is an example of using JAXP to create a transformer and then applying it to a Document.

import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;

import org.dom4j.Document;
import org.dom4j.io.DocumentResult;
import org.dom4j.io.DocumentSource;

public class Foo {

    public Document styleDocument(Document document, String stylesheet) throws Exception {

        // load the transformer using JAXP
        TransformerFactory factory = TransformerFactory.newInstance();
        Transformer transformer = factory.newTransformer( 
            new StreamSource( stylesheet ) 
        );

        // now lets style the given document
        DocumentSource source = new DocumentSource( document );
        DocumentResult result = new DocumentResult();
        transformer.transform( source, result );

        // return the transformed document
        Document transformedDoc = result.getDocument();
        return transformedDoc;
    }
}