<book> pub. September 2001 <authorgroup> Mr. Tobias Rademacher Mr. James Strachan </authorgroup>

## Revision History

Revision 0.1.0 (02-05-09)

- (tradem)

Revision 0.0.9 (02-05-01)

- (tradem)

Revision 0.0.8 (01-09-25)

- (tradem)

Revision 0.0.7 (01-09-03)

- (tradem)

Revision 0.0.6 (01-08-03)

- (jstrachan)

Revision 0.0.5 (01-07-09)

- (tradem)

Revision 0.0.4 (01-07-06)

- (tradem)

Revision 0.0.3 (01-06-20)

- (tradem)

Revision 0.0.2 (01-06-06)

- (tradem)

Revision 0.0.1 (01-06-02)

- (tradem)

<abstract>

This document provides a practical introduction to dom4j. It guides you through by using a lot of examples and is based on dom4j v1.0

</abstract> <preface>

</preface> <chapter>

<application>dom4j</application> is a object model representing an XML Tree in memory. <application>dom4j</application> offers a easy-to-use API that provides a powerful set of features to process, manipulate or navigate XML and work with XPath and XSLT as well as integrate with SAX, JAXP and DOM.

<application>dom4j</application> is designed to be interface-based in order to provide highly configurable implementation strategies. You are able to create your own XML tree implementations by simply providing a DocumentFactory implementation. This makes it very simple to reuse much of the dom4j code while extending it to provide whatever implementation features you wish.

This document will guide you through <application>dom4j</application>'s features in a practical way using a lot of examples with source code. The document is also designed as a reference so that you don't have to read the entire document at once. This guide concentrates on daily work with <application>dom4j</application> and is therefore called cookbook.

</chapter> <chapter>

Normally all starts with a set of xml-files or a single xml file that you want to process, manipulate or navigate through to extract some values necessary in your application. Most Java Open-Source projects using XML for deployment or as a replacement for property files in order to get easily readable property data.

## Reading XML data

How does <application>dom4j</application> help you to get at the data stored in XML? <application>dom4j</application> comes with a set of builder classes that parse the xml data and create a tree-like object structure in memory. You can easily manipulate and navigate through that model. The following example shows how you can read your data using <application>dom4j</application> API.

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

    public class DeployFileLoaderSample {

      /** dom4j object model representation of a xml document. Note: We use the interface(!) not its implementation */
      private Document doc;

      /**
       * Loads a document from a file.
       *
       * @throw a org.dom4j.DocumentException occurs whenever the buildprocess fails.
       */
      public void parseWithSAX(File aFile) throws DocumentException {
        SAXReader xmlReader = new SAXReader();
        this.doc = xmlReader.read(aFile);
      }
    }

The above example code should clarify the use of `org.dom4j.io.SAXReader` to build a complete <application>dom4j</application> tree from a given file. The org.dom4j.io package contains a set of classes for creation and serialization of XML objects. The read() method is overloaded so that you able to pass different kind of object that represents a source.

- `java.lang.String` - a SystemId is a String that contains a URI e.g. a URL to a XML file

- `java.net.URL` - represents a Uniform Resource Loader or a Uniform Resource Identifier. Encapsulates a URL.

- `java.io.InputStream` - an open input stream that transports xml data

- `java.io.Reader` - more compatible. Has abilitiy to specify encoding scheme

- `org.sax.InputSource` - a single input source for a XML entity.

Lets add more more flexibility to our `DeployFileLoaderSample` by adding new methods.

    import java.io.File;

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

    public class DeployFileLoaderSample {

      /** dom4j object model representation of a xml document. Note: We use the interface(!) not its implementation */
      private Document doc;

      /**
       * Loads a document from a file.
       *
       * @param aFile the data source
       * @throw a org.dom4j.DocumentExcepiton occurs on parsing failure.
       */
      public void parseWithSAX(File aFile) throws DocumentException {
        SAXReader xmlReader = new SAXReader();
        this.doc = xmlReader.read(aFile);
      }

      /**
       * Loads a document from a file.
       *
       * @param aURL the data source
       * @throw a org.dom4j.DocumentExcepiton occurs on parsing failure.
       */
      public void parseWithSAX(URL aURL) throws DocumentException {
        SAXReader xmlReader = new SAXReader();
        this.doc = xmlReader.read(aURL);
      }

    }

## Integrating with other XML APIs

<application>dom4j</application> also offers classes for integration with the two original XML processing APIs - SAX and DOM. So far we have been talking about reading a document with SAX. The `org.dom4j.SAXContentHandler` class implements several SAX interfaces directly (such as ContentHandler) so that you can embed <application>dom4j</application> directly inside any SAX application. You can also use this class to implement your own specific SAX-based Reader class if you need to.

The `DOMReader` class allows you to convert an existing DOM tree into a <application>dom4j</application> tree. This could be useful if you already used DOM and want to replace it step by step with <application>dom4j</application> or if you just needs some of DOM's behavior and want to save memory resources by transforming it in a <application>dom4j</application> Model. You are able to transform a DOM Document, a DOM node branch and a single element.

    import org.sax.Document;

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

    public class DOMIntegratorSample {

      /** converts a W3C DOM document into a dom4j document */
      public Document buildDocment(org.w3c.dom.Document domDocument) {
        DOMReader xmlReader = new DOMReader();
        return xmlReader.read(domDocument);
      }
    }

## The secret of DocumentFactory

`org.dom4j.DocumentFactory` XPath `DocumentFactory`

    import org.dom4j.DocumentFactory;
    import org.dom4j.Document;
    import org.dom4j.Element;

    public class DeployFileCreator {

      private DocumentFactory factory = DocumentFactory.getInstance();
      private Document doc;

      public void generateDoc(String aRootElement) {
        doc = DocumentFactory.getInstance().createDocument();
        Element root = doc.addElement(aRootElement);
      }

    }

The listing shows how to generate a new Document from scratch. The method `generateDoc(String aRootElement)` takes a String parameter. The string value contains the name of the root element of the new document. As you can see `org.dom4j.DocumentFactory` is a singleton accessible via `getInstance()`. The `DocumentFactory` methods follow the createXXX() naming convention. For example, if you want to create a Attribute you would call createAttribute(). If your class often calls `DocumentFactory` or uses a different DocumentFactory instance you could add it as a member variable and initiate it via getInstance in your constructor.

    import org.dom4j.DocumentFactory;
    import org.dom4j.Document;
    import org.dom4j.Element;

    public class GranuatedDeployFileCreator {

     private DocumentFactory factory;
     private Document doc;

     public GranuatedDeployFileCreator() {
       this.factory = DocumentFactory.getInstance();
     }

     public void generateDoc(String aRootElement) {
        doc = factory.createDocument();
        Element root = doc.addElement(aRootElement);
     }

    }

The `Document` and `Element` interfaces have a number of helper methods for creating an XML document programmatically in a simple way.

    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 author2 = root.addElement( "author" )
          .addAttribute( "name", "Toby" )
          .addAttribute( "location", "Germany" )
          .addText( "Tobias Rademacher" );

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

        return document;
      }
    }

As mentioned earlier <application>dom4j</application> is an interface based API. This means that DocumentFactory and the reader classes in the org.dom4j.io package always use the org.dom4j interfaces rather than any concrete implementation classes. The Collection API and W3C's DOM are other examples of APIs that use this design approach. This widespread design is described by <citation>BillVenners</citation>.

</chapter> <chapter>

Once you parsed or created a document you want to serialize it to disk or into a plain (or encrypted) stream. <application>dom4j</application> provides a set of classes to serialize your dom4j tree in four ways:

- XML

- HTML

- DOM

- SAX Events

## Serializing to XML

`org.dom4j.io.XMLWriter`<application>dom4j</application>XMLXML `java.io.OutputStream` `java.io.Writer` `setOutputStream()``setReader()`

    import java.io.OutputStream;

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

    public class DeployFileCreator {

     private Document doc;

     public void serializetoXML(OutputStream out, String aEncodingScheme) throws Exception {
       OutputFormat outformat = OutputFormat.createPrettyPrint();
       outformat.setEncoding(aEncodingScheme);
       XMLWriter writer = new XMLWriter(out, outformat);
       writer.write(this.doc);
       writer.flush();
     }

    }

We use the `XMLWriter` constructor to pass `OutputStream` along with the required character encoding. It is easier to use a `Writer` rather than an `OutputStream`, because the `Writer` is String based and so has less character encoding issues. The write() methods of `Writer` are overloaded so that you can write all of the dom4j objects individually if required.

### Customizing the output format

The default output format is to write the XML document as-is. If you want to change the output format then there is a class `org.dom4j.io.OutputFormat` which allows you to define pretty-printing options, suppress output of XML declaration, change line ending and so on. There is also a helper method `OutputFormat.createPrettyPrint()` which creates a default pretty-printing format that you can further customize if you wish.

    import java.io.OutputStream;

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

    public class DeployFileCreator {

     private Document doc;

      public void serializetoXML(OutputStream out, String aEncodingScheme) throws Exception {
       OutputFormat outformat = OutputFormat.createPrettyPrint();
       outformat.setEncoding(aEncodingScheme);
       XMLWriter writer = new XMLWriter(out, outformat);
       writer.write(this.doc);
       writer.flush();
     }

    }

An interesting feature of `OutputFormat` is the ability to set character encoding. It is a good idiom to use this mechansim for setting the encoding for XMLWriter to use this encoding to create an OutputStream as well as to output XML declaration.

The `close()` method closes the underlying `Writer`.

    import java.io.OutputStream;

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

    public class DeployFileCreator {

     private Document doc;
     private OutputFormat outFormat;

     public DeployFileCreator() {
       this.outFormat = OuputFormat.getPrettyPrinting();
     }

     public DeployFileCreator(OutputFormat outFormat) {
       this.outFormat = outFormat;
     }

     public void writeAsXML(OutputStream out) throws Exception {
       XMLWriter writer = new XMLWriter(outFormat, this.outFormat);
       writer.write(this.doc);
     }

     public void writeAsXML(OutputStream out, String encoding) throws Exception {
       this.outFormat.setEncoding(encoding);
       this.writeAsXML(out);
     }

    }

The serialization methods in our little example set encoding using `OutputFormat`. The default encoding if none is specifed is UTF-8. If you need a simple output on screen for debugging or testing you can omit setting of a `Writer` or an `OutputStream` completely as `XMLWriter` will default to `System.out`.

## Printing HTML

`HTMLWriter` takes a <application>dom4j</application> tree and formats it to a stream as HTML. This formatter is similar to `XMLWriter` but outputs the text of CDATA and Entity sections rather than the serialized format as in XML and also supports many HTML element which have no corresponding close tag such as for <BR> and <P>

    import java.io.OutputStream;

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

    public class DeployFileCreator {

     private Document doc;
     private OutputFormat outFormat;

     public DeployFileCreator() {
       this.outFormat = OuputFormat.getPrettyPrinting();
     }

     public DeployFileCreator(OutputFormat outFormat) {
       this.outFormat = outFormat;
     }

     public void writeAsHTML(OutputStream out) throws Exception {
       HTMLWriter writer = new HTMLWriter(outFormat, this.outFormat);
       writer.write(this.doc);
       writer.flush();
     }

    }

## Building a DOM tree

Sometimes it's necessary to transform your <application>dom4j</application> tree into a DOM tree, because you are currently refactoring your application. <application>dom4j</application> is very convenient for integration with older XML API's like DOM or SAX (see Generating SAX Events). Let's move to an example:

    import org.w3c.dom.Document;

    import org.dom4j.Document;
    import org.dom4j.io.DOMWriter;

    public class DeployFileLoaderSample {

      private org.dom4j.Document doc;

      public org.w3c.dom.Document transformtoDOM() {
        DOMWriter writer = new DOMWriter();
        return writer.write(this.doc);
      }
    }

## Generating SAX Events

If you want to output a document as sax events in order to integrate with some existing SAX code, you can use the `org.dom4j.SAXWriter` class.

    import org.xml.ConentHandler;

    import org.dom4j.Document;
    import org.dom4j.io.SAXWriter;

    public class DeployFileLoaderSample {

      private org.dom4j.Document doc;

      public void transformtoSAX(ContentHandler ctxHandler) {
         SAXWriter writer = new SAXWriter();
         writer.setContentHandler(ctxHandler);
         writer.write(doc);
      }
    }

As you can see using `SAXWriter` is fairly easy. You can also pass `org.dom.Element` so you are able to process a single element branch or even a single node with SAX.

</chapter> <chapter>

dom4j offers several powerful mechanisms for navigating through a document:

- Using Iterators

- Fast index based navigation

- Using a backed List

- Using XPath

- In-Build GOF Visitor Pattern

## Using Iterator

Most Java developers used java.util.Iterator or it's ancestor `java.util.Enumeration`. Both classes are part of the Collection API and used to visit elements of a collection. Here is an example of using Iterator:

    import java.util.Iterator;

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

    public class DeployFileLoaderSample {

      private org.dom4j.Document doc;
      private org.dom4j.Element root;

      public void iterateRootChildren() {
        root = this.doc.getRootElement();
        Iterator elementIterator = root.elementIterator();
        while(elementIterator.hasNext()){
          Element elmeent = (Element)elementIterator.next();
          System.out.println(element.getName());
        }
      }
    }

The above example might be a little bit confusing if you are not familiar with the Collections API. Casting is necessary when you want to access the object. In JDK 1.5 Java Generics solve this problem .

    import java.util.Iterator;

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

    public class DeployFileLoaderSample {

      private org.dom4j.Document doc;
      private org.dom4j.Element root;

      public void iterateRootChildren(String aFilterElementName) {
        root = this.doc.getRootElement();
        Iterator elementIterator = root.elementIterator(aFilterElementName);
        while(elementIterator.hasNext()){
          Element elmeent = (Element)elementIterator.next();
          System.out.println(element.getName());
        }
      }
    }

Now the the method iterates on such Elements that have the same name as the parameterized String only. This can be used as a kind of filter applied on top of Collection API's Iterator.

## Fast index based Navigation

Sometimes if you need to walk a large tree very quickly, creating an `java.io.Iterator` instance to loop through each `Element`'s children can be too expensive. To help this situation, <application>dom4j</application> provides a fast index based looping as follows.

      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....
          }
        }
      }

### Using a backed List

You can navigate through an `Element`'s children using a backed `List` so the modifications to the `List` are reflected back into the `Element`. All of the methods on `List` can be used.

    import java.util.List;

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

    public class DeployFileLoaderSample {

      private org.dom4j.Document doc;

      public void iterateRootChildren() {
        Element root = doc.getRootElement();

        List elements = root.elements;

        // we have access to the size() and other List methods
        if ( elements.size() > 4 ) {
          // now lets remove a range of elements
          elements.subList( 3, 4 ).clear();
        }
      }
    }

### Using XPath

XPath is is one of the most useful features of <application>dom4j</application>. You can use it to retrieve nodes from any location as well as evaluating complex expressions. A good XPath reference can be found in Michael Kay's XSLT book <citation>XSLTReference</citation> along with the <citation>Zvon</citation> Zvon tutorial.

    import java.util.Iterator;

    import org.dom4j.Documet;
    import org.dom4j.DocumentHelper;
    import org.dom4j.Element;
    import org.dom4j.XPath;

    public class DeployFileLoaderSample {

      private org.dom4j.Document doc;
      private org.dom4j.Element root;

      public void browseRootChildren() {

        /*
          Let's look how many "James" are in our XML Document an iterate them
          ( Yes, there are three James in this project ;) )
        */

        XPath xpathSelector = DocumentHelper.createXPath("/people/person[@name='James']");
        List results = xpathSelector.selectNodes(doc);
        for ( Iterator iter = result.iterator(); iter.hasNext(); ) {
          Element element = (Element) iter.next();
          System.out.println(element.getName();
        }

        // select all children of address element having person element with attribute and value "Toby" as parent
        String address = doc.valueOf( "//person[@name='Toby']/address" );

        // Bob's hobby
        String hobby = doc.valueOf( "//person[@name='Bob']/hobby/@name" );

        // the second person living in UK
        String name = doc.value( "/people[@country='UK']/person[2]" );

        // select people elements which have location attriute with the value "London"
        Number count = doc.numberValueOf( "//people[@location='London']" );

      }

    }

As selectNodes returns a List we can apply `Iterator` or any other operation avalilable on `java.util.List`. You can also select a single node via `selectSingleNode()` as well as to select a String expression via `valueOf()` or Number value of an XPath expression via `numberValueOf()`.

### Using Visitor Pattern

The visitor pattern has a recursive behavior and acts like SAX in the way that partial traversal is not possible. This means complete document or complete branch will be visited. You should carefully consider situations when you want to use Visitor pattern, but then it offers a powerful and elegant way of navigation. This document doesn't explain Vistor Pattern in depth, <citation>GoF98</citation> covers more information.

    import java.util.Iterator;

    import org.dom4j.Visitor;
    import org.dom4j.VisitorSupport;
    import org.dom4j.Document;
    import org.dom4j.Element;

    public class VisitorSample {

      public void demo(Document doc) {

        Visitor visitor = new VisitorSupport() {
          public void visit(Element element) {
            System.out.println(
              "Entity name: " + element.getName()  + "text " + element.getText();
            );
          }
        };

        doc.accept( visitor );
      }
    }

As you can see we used anonymous inner class to override the `VisitorSupport` callback adapter method visit(Element element) and the accept() method starts the visitor mechanism.

</chapter> <chapter>

Accessing XML content statically alone would not very special. Thus dom4j offers several methods for manipulation a documents content.

## What org.dom4j.Document provides

A `org.dom4j.Document` allows you to configure and retrieve the root element. You are also able to set the DOCTYPE or a SAX based `EntityResolver`. An empty `Document` should be created via `org.dom4j.DocumentFactory`.

## Working with org.dom4j.Element

`org.dom4j.Element` is a powerful interface providing many methods for manipulating Element.

      public void changeElementName(String aName) {
        this.element.setName(aName);
      }

      public void changeElementText(String aText) {
        this.element.setText(aText);
      }

## Qualified Names

An XML Element should have a qualified name. Normally qualified name consists normally of a Namespace and local name. It's recommended to use `org.dom4j.DocumentFactory` to create Qualified Names that are provided by `org.dom4j.QName` instances.

      import org.dom4j.Element;
      import org.dom4j.Document;
      import org.dom4j.DocumentFactory;
      import org.dom4j.QName;

      public class DeployFileCreator {

       protected Document deployDoc;
       protected Element root;

       public void DeployFileCreator()
       {
         QName rootName = DocumentFactory.getInstance().createQName("preferences", "", "http://java.sun.com/dtd/preferences.dtd");
         this.root = DocumentFactory.getInstance().createElement(rootName);
         this.deployDoc = DocumentFactory.getInstance().createDocument(this.root);
       }
      }

## Inserting elements

Sometimes it's necessary to insert an element in a existing XML Tree. This is easy to do using dom4j Collection API.

        public void insertElementAt(Element newElement, int index) {
          Element parent = this.element.getParent();
          List list = parent.content();
          list.add(index, newElement);
        }

        public void testInsertElementAt() {

        //insert an clone of current element after the current element
          Element newElement = this.element.clone();
          this.insertElementAt(newElement, this.root.indexOf(this.element)+1);

        // insert an clone of current element before the current element
          this.insertElementAt(newElement, this.root.indexOf(this.element));
        }

## Cloning - How many sheep do you need?

Elements can be cloned. Usually cloning is supported in Java with clone() method that is derived from `Object`. The cloneable Object has to implement interface `Cloneable`. By default clone() method performs shallow copying. dom4j implements deep cloning because shallow copies would not make sense in context of an XML object model. This means that cloning can take a while because the complete tree branch or event the document will be cloned. Now have a short look how dom4j cloning mechanism is used.

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

      public class DeployFileCreator {

       private Element cloneElement(String name) {
        return this.root.element(name).clone();
       }

       private Element cloneDetachElement(String name) {
         return this.root.createCopy(name);
       }

       public class TestElement extends junit.framework.TestCase {

         public void testCloning() throws junit.framwork.AssertionFailedException {
           assert("Test cloning with clone() failed!", this.creator.cloneElement("Key") != null);
           assert("Test cloning with createCopy() failed!", this.creator.cloneDetachElement() != null);
         }
       }
      }

The difference between createCopy(...) and clone() is that first method creates a detached deep copy whereas clone() returns exact copy of the current document or element.

<caution>

Cloning might be useful when you want to build element pool. Memory consumpsion should be carefully considered during design of such pool. Alternatively you can consider to use Reference API <citation>Pawlan98</citation> or Dave Millers approach <citation>JavaWorldTip76</citation>.

</caution>
</chapter> <chapter>

With eXtensible Stylesheet Language XML got a powerfull method of transformation. XML XSL greately simplified job of developing export filters for different data formats. The transformation is done by XSL Processor. XSL covers following subjects:

- XSL Style Sheet

- XSL Processor for XSLT

- FOP Processor for FOP

- An XML source

Since JaXP 1.1 TraX is the common API for proceeding a XSL Stylesheet inside of Java. You start with a `TransformerFactory`, specify `Result` and `Source`. `Source` contains source xml file that should be transformed. `Result` contains result of the transformation. dom4j offers `org.dom4j.io.DocumentResult` and `org.dom4j.io.DocumenSource` for TrAX compatibility. Whereas `org.dom4j.io.DocumentResult` contains a `org.dom4j.Document` as result tree, `DocumentSource` takes dom4j `Document`s and prepares them for transformation. Both classes are build on top of TraX own SAX classes. This approach has much better performance than a DOM adaptation. The following example explains the use of XSLT with TraX and dom4j.

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

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

    public class DocumentStyler
    {
        private Transformer transformer;

        public DocumentStyler(Source aStyleSheet) throws Exception {
            // create transformer
            TransformerFactory factory = TransformerFactory.newInstance();
            transformer = factory.newTransformer( aStyleSheet );
        }

        public Document transform(Document aDocument, Source aStyleSheet) throws Exception {

            // perform transformation
            DocumentSource source = new DocumentSource( aDocument );
            DocumentResult result = new DocumentResult();
            transformer.transform(source, result);

            // return resulting document
            return result.getDocument();
        }
    }

One could use XSLT to process a XML Schema and generate an empty template xml file according the schema constraints. The code above shows how easy to do that with dom4j and its TraX support. TemplateGenerator can be shared but for this example I avoided this for simplicity. More information about TraX is provided here.

</chapter> <chapter>

First way to describe XML document structure is as old as XML itself. Document Type Definitions are used since publishing of the XML specification. Many applications use DTD to describe and validate documents. Unfortunately the DTD Syntax was not that powerful. Written in SGML, DTDs are also not as easy to handle as XML.

Since then other, more powerful ways to describe XML format were invented. The W3C published XML Schema Specification which provides significant improvements over DTD. XML Schemas are described using XML. A growing group of people use XML Schema now. But XML Schema isn't perfect. So a few people swear by Relax or Relax NG. The reader of this document is able to choose one of the following technologies:

- Relax NG (Regular Language description for XML Next Generation)<citation>RelaxNG</citation>

- Relax (Regular Language description for XML)<citation>Relax</citation>

- TREX<citation>TREX</citation>

- XML DTDs<citation>DTD</citation>

- XML Schema<citation>XSD</citation>

## Using XML Schema Data Types in dom4j

dom4j currently supports only XML Schema Data Types <citation>DataTypes</citation>. The dom4j implementation is based on top of MSV. Earlier dom4j releases are built on top of Sun Tranquilo (xsdlib.jar) library but later moved to MSV now, because MSV provides the same Tranquilo plus exciting additional features we will discuss later.

    import java.util.List;

    import org.dom4j.Document;
    import org.dom4j.DocumentHelper;
    import org.dom4j.XPath;
    import org.dom4j.io.SAXReader;
    import org.dom4j.dataType.DataTypeElement;

    public class SchemaTypeDemo {

    public static void main(String[] args) {

      SAXReader reader = new SAXReader();
      reader.setDocumentFactory( DatatypeDocumentFactory.getInstance() );
      Document schema =  return reader.read(xmlFile)
      XPath xpathSelector = DocumentHelper.createXPath("xsd:schema/xsd:complexType[@name='Address']/xsd:structure/xsd:element[@type]");
      List xsdElements = xpathSelector.selectNodes(schema);

      for (int i=0; i < xsdElements.size(); i++) {
        DataElement tempXsdElement = (DatatypeElement)xsdElements.get(i);

        if (tempXsdElement.getData() instanceof Integer) {
           tempXsdElement.setData(new Integer(23));
         }
      }
    }

<caution>

Note that the Data Type support is still alpha. If you find any bug, please report it to the mailing list. This helps us to make more stable Data Type support.

</caution>

## Validation

Currently dom4j does not come with a validation engine. You are forced to use a external validator. In the past we recommended Xerces, but now you are able to use Sun Multi-Schema XML Validator. Xerces is able to validate against DTDs and XML Schema, but not against TREX or Relax. The Suns Multi Schema Validator supports all mentioned kinds of validation.

<caution>

Validation consumes valuable resources. Use it wisely.

</caution>

### Using Apaches Xerces 1.4.x and dom4j for validation

It is easy to use Xerces 1.4.x for validation. Download Xerces from Apaches XML web sites. Experience shows that the newest version is not always the best. View Xerces mailing lists in order to find out issues with specific versions. Xerces provides Schema support strarting from 1.4.0.

- Turn on validation mode - which is false for default - using a SAXReader instance

- Set the following Xerces property http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation using the schema URI.

- Create a SAX XMLErrorHandler and install it to your SAXReader instance.

- Parse and validate the Document.

- Output Validation/Parsing errors.

    import org.dom4j.Document;
    import org.dom4j.Element;
    import org.dom4j.io.OutputFormat;
    import org.dom4j.io.SAXReader;
    import org.dom4j.io.XMLWriter;
    import org.dom4j.util.XMLErrorHandler;

    import org.xml.sax.ErrorHandler;
    import org.xml.sax.SAXParseException

    public class SimpleValidationDemo {

    public static void main(String[] args) {
      SAXReader reader = new SAXReader();

      reader.setValidation(true);

      // specify the schema to use
      reader.setProperty(
       "http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation",
       "prices.xsd"
      );

      // add error handler which turns any errors into XML
       XMLErrorHandler errorHandler = new XMLErrorHandler();
       reader.setErrorHandler( errorHandler );

      // parse the document
      Document document = reader.read(args[0]);

     // output the errors XML
      XMLWriter writer = new XMLWriter( OutputFormat.createPrettyPrint() );
      writer.write( errorHandler.getErrors() );
    }

<caution>

Both, Xerecs and Crimson, are JaXPable parsers. Be careful while using Crimson and Xerces in same class path. Xerces will work correctly only when it is specified in class path before Crimson. At this time I recommend that you should either Xereces or Crimson.

</caution>

### A perfect team - Multi Schema ValidatorMSV and dom4j

Kohsuke Kawaguchi a developer from Sun created a extremly usefull tool for XML validation. Multi Schema Validator (MSV) supports following specifications:

- Relax NG

- Relax

- TREX

- XML DTDs

- XML Schema

Currently its not clear whether XML Schema will be the next standard for validation. Relax NG has an ever more growing lobby. If you want to build a open application that is not fixed to a specific XML parser and specific type of XML validation you should use this powerfull tool. As usage of MSV is not trivial the next section shows how to use it in simpler way.

### Simplified Multi-Schema Validation by using Java API for RELAX Verifiers (JARV)

The Java API for RELAX Verifiers <citation>JARV</citation> defines a set of Interfaces and provide a schemata and vendor neutral API for validation of XML documents. The above explained MSV offers a Factory that supports JARV. So you can use the JARV API on top of MSV and dom4j to validate a dom4j documents.

    import org.iso_relax.verifier.Schema;
    import org.iso_relax.verifier.Verifier;
    import org.iso_relax.verifier.VerifierFactory;
    import org.iso_relax.verifier.VerifierHandler;

    import com.sun.msv.verifier.jarv.TheFactoryImpl;

    import org.apache.log4j.Category;

    import org.dom4j.Document;
    import org.dom4j.io.SAXWriter;

    import org.xml.sax.ErrorHandler;
    import org.xml.sax.SAXParseException;

    public class Validator {

      private final static CATEGORY = Category.getInstance(Validator.class);
      private String schemaURI;
      private Document document;

      public Validator(Document document, String schemaURI) {
        this.schemaURI = schemaURI;
        this.document = document;
      }

      public boolean validate() throws Exception {

        // (1) use autodetection of schemas
        VerifierFactory factory = new com.sun.msv.verifier.jarv.TheFactoryImpl();
        Schema schema = factory.compileSchema( schemaURI );

        // (2) configure a Vertifier
        Verifier verifier = schema.newVerifier();
            verifier.setErrorHandler(
                new ErrorHandler() {
                    public void error(SAXParseException saxParseEx) {
                       CATEGORY.error( "Error during validation.", saxParseEx);
                    }

                    public void fatalError(SAXParseException saxParseEx) {
                       CATEGORY.fatal( "Fatal error during validation.", saxParseEx);
                    }

                    public void warning(SAXParseException saxParseEx) {
                       CATEGORY.warn( saxParseEx );
                    }
                }
            );

        // (3) starting validation by resolving the dom4j document into sax
        VerifierHandler handler = verifier.getVerifierHandler();
        SAXWriter writer = new SAXWriter( handler );
        writer.write( document );

        return handler.isValid();
      }

      }

    }

The whole work in the above example is done in <methodname>validate()</methodname> method. Foremost the we create a Factory instance and use it to create a JAVR `org.iso_relax.verifier.Schema` instance. In second step we create and configure a `org.iso_relax.verifier.Verifier` using a `org.sax.ErrorHandler`. I use Apaches Log4j API to log possible errors. You can also use <methodname>System.out.println()</methodname> or, depending of the applications desired robustness, any other method to provide information about failures. Third and last step resolves the `org.dom4j.Document` instance using SAX in order to start the validation. Finally we return a boolean value that informs about success of the validation.

Using teamwork of dom4j, MSV, JAVR and good old SAX simplifies the usage of multi schemata validation while gaining the power of MSV.

</chapter> <chapter>

XSLT defines a declarative rule-based way to transform XML tree into plain text, HTML, FO or any other text-based format. XSLT is very powerful. Ironically it does not need variables to hold data. As Michael Kay <citation>XSLTReference</citation> says: "This style of coding without assignment statements, is called Functional Programming. The earliest and most famous functional programming language was Lisp ..., while modern examples include ML and Scheme." In XSLT you define a so called template that matches a certain XPath expression. The XSLT Processor traverse the source tree using a recursive tree descent algorithm and performs the commands you defined when a specific tree branch matches the template rule.

dom4j offers an API that supports XSLT similar rule based processing. The API can be found in `org.dom4j.rule` package and this chapter will introduce you to this powerful feature of dom4j.

## Introducing dom4j's declarative rule processing

This section will demonstrate the usage of dom4j's rule API by example. Consider we have the following XML document, but that we want to transform into another XML document containing less information.

        <?xml version="1.0" encoding="UTF-8" ?>
        <Songs>
         <song>
           <mp3 kbs="128" size="6128">
             <id3>
              <title>Simon</title>
              <artist>Lifehouse</artist>
              <album>No Name Face</album>
              <year>2000</year>
              <genre>Alternative Rock</genre>
              <track>6</track>
             </id3>
           </mp3>
          </song>
          <song>
           <mp3 kbs="128" size="6359">
             <id3>
              <title>Hands Clean</title>
              <artist>Alanis Morrisette</artist>
              <album>Under Rug Swept</album>
              <year>2002</year>
              <genre>Alternative Rock</genre>
              <track>3</track>
             </id3>
           </mp3>
          </song>
          <song>
           <mp3 kbs="256" size="6460">
             <id3>
              <title>Alive</title>
              <artist>Payable On Deatch</artist>
              <album>Satellit</album>
              <year>2002</year>
              <genre>Metal</genre>
              <track/>
             </id3>
           </mp3>
           <mp3 kbs="256" size="4203">
             <id3>
              <title>Crawling In The Dark</title>
              <artist>Hoobastank</artist>
              <album>Hoobastank (Selftitled)</album>
              <year>2002</year>
              <genre>Alternative Rock</genre>
              <track/>
             </id3>
           </mp3>
         </song>
        </Songs>

A common method to transform one XML document into another is XSLT. It's quite powerful but it is very different from Java and uses paradigms different from OO. Such style sheet may look like this.

          <xsl:stylesheet version="1.0"
               xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
               xmlns:fo="http://www.w3.org/1999/XSL/Format"
           >
            <xsl:output method="xml" indent="yes"/>

            <xsl:template match="/">
             <Song-Titles>
               <xsl:apply-templates/>
             </Song-Tiltes>
            </xsl:template>

            <xsl:template match="/Songs/song/mp3">
              <Song>
                <xsl:apply-template/>
              </Song>
            </xsl:template>

            <xsl:template match="/Songs/song/mp3/title">
              <xsl:text> <xsl:value-of select="."/> </xsl:text>
            </xsl:template>

          </xsl:stylesheet>

This stylesheet filters all song titles and creates a xml wrapper for it. After applying the stylesheet with XSLT processor you will get the following xml document.

          <?xml version="1.0" encoding="UTF-8" ?>
          <Song-Titles>
     	<song>Simon</song>
    	<song>Hands Clean</song>
            <song>Alive</song>
            <song>Crawling in the Dark</song>
          </Song-Titles>

Okay. Now it's time to present a possible solution using dom4j's rule API. As you will see this API is very compact. The Classes you have to write are neither complex nor extremely hard to understand. We want to get the same result as your former stylesheet.

<programlistingco> <areaspec> </areaspec>

      import java.io.File;

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

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

      import org.dom4j.rule.Action;
      import org.dom4j.rule.Pattern;
      import org.dom4j.rule.Stylesheet;
      import org.dom4j.rule.Rule;

      public class SongFilter {

        private Document resultDoc;
        private Element songElement;
        private Element currentSongElement;
        private Stylesheet style;

        public SongFilter() {
            this.songElement = DocumentHelper.createElement( "song" );
        }

        public Document filtering(org.dom4j.Document doc) throws Exception {
            Element resultRoot = DocumentHelper.createElement( "Song-Titles" );
            this.resultDoc = DocumentHelper.createDocument( resultRoot );

            Rule songElementRule = new Rule();
            songElementRule.setPattern( DocumentHelper.createPattern( "/Songs/song/mp3/id3" ) );
            songElementRule.setAction( new SongElementBuilder() );

            Rule titleTextNodeFilter = new Rule();
            titleTextNodeFilter.setPattern( DocumentHelper.createPattern( "/Songs/song/mp3/id3/title" ) );
            titleTextNodeFilter.setAction( new NodeTextFilter() );

            this.style = new Stylesheet();
            this.style.addRule( songElementRule );
            this.style.addRule( titleTextNodeFilter );

            style.run( doc );

            return this.resultDoc;
        }

        private class SongElementBuilder implements Action {
            public void run(Node node) throws Exception {
               currentSongElement = songElement.createCopy();
               resultDoc.getRootElement().add ( currentSongElement );

               style.applyTemplates(node);
            }
        }

        private class NodeTextFilter implements Action {
            public void run(Node node) throws Exception {
              if ( currentSongElement != null )
              {
                currentSongElement.setText( node.getText() );
              }
            }
        }

    }

<calloutlist>

Define the root element or another container element for the filtered out information.

Create as many instances of `org.dom4j.rule.Rule` as needed.

Install for each rule a instance of `org.dom4j.rule.Pattern` and `org.dom4j.rule.Action`. A `org.dom4j.rule.Pattern` consists of a XPath Expression, which is used for Node matching.

A `org.dom4j.rule.Action` defines the process if a matching occured.

Create a instance of `org.dom4j.rule.Stylesheet`

Start the processing

</calloutlist> </programlistingco>

If you are familiar with Java Threads you may encounter usage similarities between `java.lang.Runnable` and `org.dom4j.rule.Action`. Both act as a plugin or listener. And this Observer Pattern has a wide usage in OO and especially in Java. We implemented observers here as private inner classes. You may decide to declare them as outer classes as well. However if you do that, the design becomes more complex because you need to share instance of `org.dom4j.rule.StyleSheet`.

<note>

Moreover it's possible to create an anonymous inner class for `org.dom4j.rule.Action` interface.

</note>

## Understanding dom4j's rule API

Visitor | Declartive Rule Processing
--- | ---
Use of Interfaces in design | Use of Interfaces in design
Uncontrolled automatic recursive descent traversal | Rule controlled automatic recursive descent traversal
Needs knowledge of Visitor pattern to understand | Knowledge of Observer/Publish-Subscriber pattern (ligua franca pattern besides Singleton) useful
Provides adapater class to simplify usage of interface | Adapter not necessary due to interface using single method
Basic knowledge of dom4j's tree object model necessary | Additional XPath knowlege for pattern specification necessary
Implementation is more compact | More code necessary to define the rules and action
High and easy modularity | High modularity for controlled recursive processing, but more complex handling if you abandon inner or anonymous inner classes.

As shown above, dom4j's uses a very flexible OO-Representation of a XSLT Stylesheet. The smart handling of actions produces compact code.

The rule API is a OO representation of W3C XSLT. The API defines another way of traversing the in-memory dom4j tree. The traversal algorithm is called recursive descent and is the same as XSLT defines. Such algorithms are also used in compiler construction and described in literature.

XSLT defines a way of tree merging or filtering. If you output an eXtensible stylesheet result to another xml you merge an existing tree to another one using the instruction of the Stylesheet and if output to plain text a styling is used for filtering. First usage is addressed by this API. The second is also possible but not so easy to implement as in XSLT.

How does the rule API work? Each Stylesheet has a rule. A rule consists of an action and a pattern. Patterns are described with XPath. You start the processing of a Stylesheet on a specific source with must be a dom4j `Node`. Calling method `style.applyTemplates(node);` traverses the `Node` using a recursive descent algorithm - branch after branch. If a pattern matches the assigned action is activated.

If you are interested more in the way a xml document is traversed by XSLT processors I recommend Michael Kay's book <citation>XSLTReference</citation>.

</chapter> <bibliography> <bibliodiv> <biblioentry> <abbrev>XSLTReference</abbrev> <authorgroup> Michael Kay </authorgroup>

Copyright ©2001 by Worx Press, Inc..
All rights reserved.

<isbn>1-861-005067</isbn> <publisher> <publishername>Worx Press</publishername> </publisher> <seriesinfo> <publisher> <publishername>Worx Press</publishername> </publisher> </seriesinfo> </biblioentry> <biblioentry> <abbrev>GoF95</abbrev> <authorgroup> Erich Gamma Richard Helm Ralph Johnson John Vlissides </authorgroup>

Copyright ©1995 by Addison Wesley Pub, Co..
All rights reserved.

<isbn>0-201-633-612</isbn> <publisher> <publishername>Addison-Wesley</publishername> </publisher> </biblioentry> </bibliodiv> </bibliography> <bibliodiv> <biblioentry> <abbrev>Pawlan98</abbrev> <authorgroup> Monica Pawlan </authorgroup>

Copyright ©1998 by http://developer.java.sun.com/javatips/jw-tips76.html.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>JavaTip76</abbrev> <authorgroup> Dave Miller </authorgroup>

Copyright © by http://www.javaworld.com/javaworld/javatips/jw-javatip76.html.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>BillVenners</abbrev> <authorgroup> Bill Venners </authorgroup>

Copyright © by http://www.artima.com/designtechniques/interfaces.html.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>Zvon</abbrev>

Copyright © by http://www.zvon.org/xxl/XPathTutorial/General/examples.html.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>RelaxNG</abbrev>

Copyright © by http://www.oasis-open.org/committees/relax-ng/.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>Relax</abbrev>

Copyright © by http://www.xml.gr.jp/relax/.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>TREX</abbrev>

Copyright © by http://www.thaiopensource.com/trex/.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>DTD</abbrev>

Copyright © by http://www.w3schools.com/dtd/default.asp.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>XSD</abbrev>

Copyright © by http://www.w3.org/XML/Schema http://www.w3.org/XML/1998/06/xmlspec-report.
All rights reserved.

</biblioentry> <biblioentry> <abbrev>JARV</abbrev>

Copyright © by http://iso-relax.sourceforge.net/JARV/.
All rights reserved.

</biblioentry> </bibliodiv> </book>