pub. September 2001 Mr. Tobias Rademacher Mr. James Strachan

Revision History

Revision 0.1.0 (02-05-09)

Revision 0.0.9 (02-05-01)

Revision 0.0.8 (01-09-25)

Revision 0.0.7 (01-09-03)

Revision 0.0.6 (01-08-03)

Revision 0.0.5 (01-07-09)

Revision 0.0.4 (01-07-06)

Revision 0.0.3 (01-06-20)

Revision 0.0.2 (01-06-06)

Revision 0.0.1 (01-06-02)

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

dom4j is a object model representing an XML Tree in memory. dom4j 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.

dom4j 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 dom4j'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 dom4j and is therefore called cookbook.

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 dom4j help you to get at the data stored in XML? dom4j 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 dom4j 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 dom4j 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

dom4j 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 dom4j 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 dom4j tree. This could be useful if you already used DOM and want to replace it step by step with dom4j or if you just needs some of DOM's behavior and want to save memory resources by transforming it in a dom4j 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.DocumentFactoryXPathDocumentFactory

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 dom4j 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 BillVenners.

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

Serializing to XML

org.dom4j.io.XMLWriterdom4jXMLXMLjava.io.OutputStreamjava.io.WritersetOutputStream()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 dom4j 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 dom4j tree into a DOM tree, because you are currently refactoring your application. dom4j 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.

dom4j offers several powerful mechanisms for navigating through a document:

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, dom4j 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 dom4j. 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 XSLTReference along with the Zvon 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, GoF98 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.

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.

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 Pawlan98 or Dave Millers approach JavaWorldTip76.

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:

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

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:

Using XML Schema Data Types in dom4j

dom4j currently supports only XML Schema Data Types DataTypes. 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));
     }
  }
}

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.

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.

Validation consumes valuable resources. Use it wisely.

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() );
}

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.

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 JARV 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 validate() 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 System.out.println() 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.

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

  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() );
          }
        }        
    }
        
      
}

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

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.

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

Understanding dom4j's rule API

VisitorDeclartive Rule Processing
Use of Interfaces in designUse of Interfaces in design
Uncontrolled automatic recursive descent traversalRule controlled automatic recursive descent traversal
Needs knowledge of Visitor pattern to understandKnowledge of Observer/Publish-Subscriber pattern (ligua franca pattern besides Singleton) useful
Provides adapater class to simplify usage of interfaceAdapter not necessary due to interface using single method
Basic knowledge of dom4j's tree object model necessaryAdditional XPath knowlege for pattern specification necessary
Implementation is more compactMore code necessary to define the rules and action
High and easy modularityHigh 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 XSLTReference.

XSLTReference Michael Kay

Copyright ©2001 by Worx Press, Inc..

All rights reserved.

1-861-005067 Worx Press Worx Press GoF95 Erich Gamma Richard Helm Ralph Johnson John Vlissides

Copyright ©1995 by Addison Wesley Pub, Co..

All rights reserved.

0-201-633-612 Addison-Wesley Pawlan98 Monica Pawlan

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

All rights reserved.

 JavaTip76 Dave Miller

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

All rights reserved.

 BillVenners Bill Venners

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

All rights reserved.

 Zvon

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

All rights reserved.

 RelaxNG

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

All rights reserved.

 Relax

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

All rights reserved.

 TREX

Copyright © by http://www.thaiopensource.com/trex/.

All rights reserved.

 DTD

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

All rights reserved.

 XSD

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

All rights reserved.

 JARV

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

All rights reserved.