-
Notifications
You must be signed in to change notification settings - Fork 240
Cookbook
This document provides a practical introduction to dom4j. It guides you through by using a lot of examples.
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.
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);
}
}
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);
}
}
We have talked a lot of reading existing XML information e.g. from files, URL's or even Streams.
Sometimes it's necessary to generate a XML document programmatically.
The class org.dom4j.DocumentFactory
defines a set of factory methods to create documents, document
types, elements, attributes, unparsed character data (CDATA), a namespace, an XPath object, a NodeFilter and
some other useful instances. This makes the DocumentFactory
a central class whenever you have to create
one of these instances by yourself.
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:
- XML
- HTML
- DOM
- SAX Events
org.dom4j.io.XMLWriter
is a easy-to-use and easy-to-understand class used
to serialize a dom4j tree to a plain XML.
You are able
to write the XML tree to either an java.io.OutputStream
or a java.io.Writer
.
This can be configured with the overloaded constructor or via the
setOutputStream()
or setReader()
methods.
Let's have a look at a example.
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.
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
.
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();
}
}
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);
}
}
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.ContentHandler;
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 Iterators
- Fast index based navigation
- Using a backed List
- Using XPath
- In-Build GOF Visitor Pattern
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.
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....
}
}
}
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();
}
}
}
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()
.
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.
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
.
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);
}
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);
}
}
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));
}
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:
- 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.
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)RelaxNG
- Relax (Regular Language description for XML)Relax
- TREXTREX
- XML DTDsDTD
- XML SchemaXSD
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.
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.
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.
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.
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.
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.
<![CDATA[
<?xml version="1.0" encoding="UTF-8" ?>
<Songs>
<song>
<mp3 kbs="128" size="6128">
<id3>
<title>Simon
<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
<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
<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
<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.
<areaspec>
<areaset id="example.rule.step1" coord="">
<area id="example.rule.root" coords='32'/>
<area id="example.rule.doc" coords='33'/>
</areaset>
<areaset id="example.rule.step2">
<area id="example.rule.rule1" coords="35"/>
<area id="example.rule.rule2" coords="39"/>
</areaset>
<areaset id="example.rule.step3">
<area id="example.rule.pattern1" coords="36"/>
<area id="example.rule.action1" coords="37"/>
<area id="example.rule.pattern2" coords="40"/>
<area id="example.rule.action2" coords="41"/>
</areaset>
<areaset id="example.rule.step4">
<area id="example.rule.actionclass1" coords="55"/>
<area id="example.rule.actionclass2" coords="64"/>
</areaset>
<area id="example.rule.step5" coords="43"/>
<area id="example.rule.step6" coords="47"/>
</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() );
}
}
}
}
(1) Define the root element or another container element for the filtered out information.
(2) Create as many instances of org.dom4j.rule.Rule
as needed.
(3) 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.
(4) A org.dom4j.rule.Action
defines the process if a matching occured.
(5) Create a instance of org.dom4j.rule.Stylesheet
(6)Start the processing
Following steps are recommended to use this API correctly.
- Define 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
andorg.dom4j.rule.Action
. Aorg.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 occurred.
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.
Comparing Visitor with 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 XSLTReference.