What is JDOM

JDOM is an in-memory XML model that can be used to read, write, create and modify XML Documents. JDOM is similar to DOM in that they both provide an in-memory XML document model, but while DOM is designed to work the same in multiple languages (C, C++, ECMAScript, Java, JScript, Lingo, PHP, PLSQL, and Python [http://www.w3.org/DOM/Bindings]), JDOM is designed only for Java and uses the natural Java-specific features that the DOM model avoids. For this reason JDOM intentionally does not follow the w3c DOM standard. JDOM is not an XML parser but it can use a SAX, StAX or DOM parser to build the JDOM document. JDOM versions since JDOM 2.0.0 (JDOM2) all use the native language features of Java6 and later like Generics, Enums, var-args, co-variant return types, etc.

In the tutorials listed below we provide you with examples of all key functionalities of JDOM2. However before you start seeing the examples, it would be a good idea to understand the main packages that form part of JDOM2 and the functionalities that each of the packages provide. The first tutorial in the series provides an introduction to the package structure along with important classes in each package. The subsequent tutorials provide examples for each of the key functionalities.

1. JDOM2 package structure - Introduces the package structure and explains the important classes that form the API
2. JDOM2 Usage - An introduction to building and using JDOM2 Document.
3. SAXBuilder Example
4. SAXBuilder with DTD validation
5. SAXBuilder with XSD validating - This tutorial explains how create a JDOM2 from an XML using a SAX parser by validating the document using an XSD. The example explains how to validate using an internal XSD as well as an external XSD
6. SAXBuilder - A discussion on various components of SAXBuilder and ways to configure it
7. DOMBuilder - A tutorial on building a JDOM2 document from a w3c Document using DOMBuilder.
8. Building JDOM2 using StAX
9. Filters
10. Namespaces
11. Outputter - In this tutorial we learn how to output JDOM2 as XML, DOM, SAX, StAXEvent and StaxStream
12. Transforming the JDOM2 document using XSL
13. Querying a JDOM2 document using Xpath

Acknowledgement - We thank Rolf Lear for reviewing the tutorials and giving us a detailed feedback on the pages.


If you like the tutorial then please put in your comments and also ‘like‘ us on facebook or follow us on google.

In this tutorial we explore the package structure and important classes for Jdom2.

org.jdom2

This package contains the core classes that represent the XML components.

• Document - Represents the complete XML document. It provides access to the root element and also the docType.
• DocType - Represents an XML DOCTYPE.
• Element - Represents an XML element. Has methods to manipulate the child elements, its textual content, attributes and namespaces.
• Attribute - This represents an XML attribute. There are methods to get and set the value of the attribute and also the namespace. The Attribute has a parent and an AttributeType.
• Namespace - Represents an XML Namespace.
• CDATA - This represents an XML CDATA section.
• Text - This represents an XML Text.
• Comment - Represents an XML comment. Users can get and set comment text.
• EntityRef - Represents an XML EnityRef.
• ProcessingInstruction - Represents an XML Processing Instruction
• Content - This is an abstract class which is extended by those classes that can be a child of a org.jdom2.Parent class (Element, CDATA, Comment, DocType, EntityRef, ProcessingInstruction, Text)

org.jdom2.filter

These package has filters that allow filtering based on type, name, value or other parameters. It also allows ANDing, ORing and Negating filters. Filters are used in the public <E extends Content> List<E> getContent(final Filter<E> filter) and public <F extends Content> IteratorIterable<F> getDescendants(final Filter<F> filter) methods of the Element class. Filters are also using in the XPath package of JDom2.

org.jdom2.input

This package has the core classes responsible for building the JDOM2 document from DOM, SAX or StAX. The important classes are

• SAXBuilder - Builds a JDOM document from SAX parser.
• DOMBuilder - Builds a JDOM document from pre-existing org.w3c.dom.DOM document.
• StaxEventBuilder - Builds a JDOM document from StAX XMLEventReader
• StaxStreamBuilder - Builds a JDOM document from StAX XMLStreamReader

org.jdom2.output

These package has classes to ouput the JDOM2 document to various destinations. The main classes are :

• XMLOutputter - Output a JDOM2 document as a stream of bytes.
• DOMOutputter - Convert a JDOM2 document into a DOM document. It can also convert various JDOM2 components to its equivalent DOM components
• SAXOutputter - Convert a JDOM2 document into a stream of SAX events
• StAXEventOutputter - output a JDOM2 document to an XMLEventWriter.
• StAXStreamOutputter - Output a JDOM2 document to an XMLStreamWriter.

Other Packages

• org.jdom2.transform - Helps with XML transformation using JAXP TrAX classes.
• org.jdom2.xpath - Support for XPath in JDOM2. By default, it uses the Jaxen xpath library

Building JDOM2 Document

In this tutorial we look at an example of how to build and navigate through a JDOM2 document from an XML source (in this case, a BBC News "Technology" RSS feed). We first use the org.jdom2.input.SAXBuilder class to create the JDOM2 document from the source (more details and options on the SAXBuilder class will be covered in later tutorials). Once we obtain the JDOM2 Document there are various JDOM2 methods used to access the elements, which will be covered in the next section of this tutorial.

Accessing JDOM2 Components

JDOM2 is a java representation of an XML document. In other words, each XML component is represent as a java object. JDOM2 has convenient methods to access the various components. Here are some of the key use cases (the number in the bracket corresponds to the line number in the example) :

• Obtaining the root element (25,28) - Root Element is the topmost Element of the document
• Obtaining the Namespace added by a node (32)
• Obtaining the contents of a particular node (43) - The node is traveresed recursively till all content is found
• Obtaining a child of an Element (50)
• Obtaining all children of an Element(54)
• Obtaining the first child of a particular type and name e.g. the first text node with name ‘link‘ (62)
• Obtaining the first child of a particular type and name and from a specified namespace e.g. the first text node with name ‘link‘ from namespace ‘atom‘(70)
• Obtaining all children with a specific name (75)
• Iterating through all the descendants of an Element and obtaining Elements with specific name and from a specific Namespace (85)

This is not an exhaustive list of use cases but it gives an idea of what can be achieved. If you have a specific requirement then do post it as a comment and we would be glad to answer it

In this tutorial we look at how to build a JDOM2 using a SAXBuilder. To understand how SAXBuilder works and how to configure it look at this tutorial. The example below demonstrates the following

• Building a JDOM2 document using a SAXBuilder.
• Obtaining the DOCTYPE of the document.
• Obtaining the root element of the document
• Obtaining a specific child (specify name) of an element
• Iterating through the descendants of an Element and printing the values of all elements whose type is not Text or Comment
• Iterating through the descendants of an Element and printing the elements of type Comment (using a Comment filter)

The example below uses the tomcat web.xml file which can be downloaded from here

In this tutorial we look at how to use SAXBuilder to create a JDOM2 Document such that the SAXBuilder validates the XML using the DTD before creating the JDOM2 document. If you are looking for a way to create JDOM2 Document using the SAXBuilder but without any validation then this tutorial explains just that.

We explain the validation using two XML document. The first XML is invalid and therefore fails the validation step. The second XML is valid.

In the earlier tutorials we saw how to build a JDOM2 document using SAXBuilder. We also saw how to validate the document using DTD while using the SAXBuilder. In this tutorial we look at how to use the SAXBuilder that validates against an XSD. The example below shows how to use an internally defined XSD. The example after that shows how to define an XSD externally.

Download tomcat-web-xsd-bad.xml and tomcat-web-xsd.xml for the example above. Now lets look at an example that shows how to specify an XSD externally. The example below specifies two methods to specify an XSD externally. Download commons-dbcp-pom.xml and maven-4.0.0.xsd for the example below.

The Plot

SAXBuilder provides methods to build JDOM2 Documents using a third party SAX Parser. It has three parts

• A SAX Parser to parse the XML document. The default Parser is JAXP.
• A SAX Handler to handle SAX events.
• A JDOM2 Factory to build the JDOM2 Document

This tutorial introduces the various classes that form part of the SAXBuilder suite. The understanding of these classes is important if you want to customize any part of the process. i.e. if you want to validate the XML (DTD, XMLSchema, etc.), if you want to use a different SAX parser or if you want your own SAXHandler or JDOM2 Factory.

The Actors (Classes)

• SAXBuilder - This is what the tutorial is all about. The following constructors are available:
  • SAXBuilder() - Uses the default parser, SAX Handler and JDOM2 Factory
  • SAXBuilder(final XMLReaderJDOMFactory readersouce) - Specify a factory to create an XMLReader. Users can also specify any of the three enum singletons : XMLReaders.NONVALIDATING, XMLReaders.DTDVALIDATING and XMLReaders.XSDVALIDATING. What this does is tell the parsers whether it should be validating the XML and if it should use DTD or XSD for validation.
  • SAXBuilder(final XMLReaderJDOMFactory xmlreaderfactory, final SAXHandlerFactory handlerfactory,final JDOMFactory jdomfactory) - Uses custom factories for parsing, SAX event handling and JDOM2 document building
  The most important methods are build(...). When you call the build methods the builder will first get the SAXEngine and then call the build method of the SAXEngine. The build method of the SAXEngine calls the parser to parse the xml. The SAXEngine has access to the SAXHandler and JDOM2 Factory and it starts building the JDOM2 Document as it parses the XML
• SAXBuilderEngine - This is created by the SAXBuilder and it parses the XML and builds a JDOM2 Document. In high performance applications you can reuse the SAXBuilderEngine multiple times without any parser reconfiguration overhead, and you can create multiple SAXBuilderEngine instances from a single configured SAXBuilder.
• XMLReaderJDOMFactory - This factory creates the XMLReaders (parsers). The createXMLReader() method creates the XMLReaders. This method is called by the SAXBuilder when it builds the SAXEngine.There are five implementations provided (though you can add your own custom ones if needed). Three of them are singletons of the enum org.jdom2.input.sax.XMLReaders. Lets look at them first
  • XMLReaders.NONVALIDATING, XMLReaders.DTDVALIDATING, XMLReaders.XSDVALIDATING - These are singleton enums for performance and convenience. They use the standard Java JAXP process for identifying and instantiating the XML parser to use, and the different singletons will either perform no XML Validation (just the regular well-formedness checks), DTD Validation, or XMLSchema validation.
  • org.jdom2.input.sax.XMLReaderSchemaFactory - Use this factory if you want to create an XMLReader that uses an external schema for validation. The schema can be any schema that is supported by SAX.
  • org.jdom2.input.sax.XMLReaderXSDFactory - Use this factory if you want to create an XMLReader that uses an external XML Schema for validation
• SAXHandlerFactory - Instances of this factory are responsible for creating Handlers that handle SAX events (fired by the SAX Parser). Let us look at the various classes that take part in SAX event handling process
  • DefaultSAXHandlerFactory - This is the default implementation of SAXHandlerFactory. It returns the DefaultSAXHandler which is just a wrapper over org.jdom2.input.sax.SAXHandler
  • SAXHandler - This class is responsible for handling SAX events produced by the XMLReader. It also takes in the JDOMFactory. If the XMLReader supports document locator for line and column number then the SAXHandler will supply that to the JDOMFactory
• JDOMFactory- This is the last piece of the puzzle. Instances of this factory create the JDOM2 Classes that are part of the JDOM2 structure. The important classes are :
  • org.jdom2.DefaultJDOMFactory - This creates the standard JDOM2 classes.
  • org.jdom2.LocatedJDOMFactory - This creates the JDOM2 classes that have implemented the org.jdom2.located.Located interface
  • org.jdom2.SlimJDOMFactory - This creates the JDOM2 content that occupies less memory by reusing string instances

Buliding JDOM2 documents from w3c DOM

JDOM2 provides a DOMBuilder that can be used to build a JDOM2 Document from a org.w3c.dom.Document. If there are namespace declarations in the xml document then make sure that while parsing the XML document the setNamespaceAware method of the DocumentBuilderFactory is set to true. Before we look at an example note that it is recommended to use a SAXBuilder to build a JDOM2 Document instead of a DOMBuilder since there is no reason to have both the DOM and JDOM2 Document in memory. Lets look at an example now.

package com.studytrails.xml.jdom;

import java.io.IOException;
import java.util.List;

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;

import org.jdom2.Document;
import org.jdom2.Element;
import org.jdom2.input.DOMBuilder;
import org.xml.sax.SAXException;

public class CreateJdomFromDom {

	private static String xmlSource = "http://feeds.bbci.co.uk/news/technology/rss.xml?edition=int";

	public static void main(String[] args) throws ParserConfigurationException, SAXException, IOException {
		// create the w3c DOM document from which JDOM is to be created
		DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
		// we are interested in making it namespace aware.
		factory.setNamespaceAware(true);
		DocumentBuilder dombuilder = factory.newDocumentBuilder();

		org.w3c.dom.Document w3cDocument = dombuilder.parse(xmlSource);

		// w3cDocument is the w3c DOM object. we now build the JDOM2 object

		// the DOMBuilder uses the DefaultJDOMFactory to create the JDOM2
		// objects.
		DOMBuilder jdomBuilder = new DOMBuilder();

		// jdomDocument is the JDOM2 Object
		Document jdomDocument = jdomBuilder.build(w3cDocument);

		// The root element is the root of the document. we print its name
		System.out.println(jdomDocument.getRootElement().getName()); // prints
																		// "rss"
		
	}
}

In the previous examples we saw how to bulid a JDOM2 document from w3c Document. We also saw how to build a JDOM2 Document using a SAXBuilder. In this example we look at how to create a JDOM2 document using a StAXEventBuilder or a StAXStreamBuilder.

StAXEventBuilder

StAXEventBuilder builds a JDOM2 document using a StAX based XMLEventReader. We first create an XMLInputFactory. We then use the factory to create an XMLEventReader by passing the XML file. The XMLEventReader is then passed to the StAXEventBuilder. Note that StAXEvenBuilder has no control over the validation process and therefore to create a validating builder set the appropriate property on the XMLInputFactory. Here‘s an example. The XML file can be downloaded from here

StAXStreamBuilder

StAXStreamBuilder builds a JDOM2 document from a StAX based XMLStreamReader. For JDOM2 XMLStreamReader is more efficient then XMLEventReader and should be the first choice. Here‘s an example

JDOM2 has three methods that accepts Filters while obtaining data. The three methods are

• <E extends Content> List<E> getContent(Filter<E> filter);
• <E extends Content> List<E> removeContent(Filter<E> filter);
• <E extends Content> IteratorIterable<E> getDescendants(Filter<E> filter);

Filters are also extensively used in the JDOM2 XPath API, especially to ‘coerce the xpath result data in to the generic-typed results‘. See this tutorial on xpath to understand how Filters are used in the JDOM2 XPath API.
The main classes are :

1. org.jdom2.filter.AbstractFilter - Contains partial implementation of org.jdom2.filter.Filter
2. org.jdom2.filter.ContentFilter - Filters various JDOM2 objects such as ELEMENT, CDATA, TEXT, COMMENT, PI, ENTITYREF, DOCUMENT and DOCTYPE. It can also filter a group of Objects such as both ELEMENT and COMMENT.
3. org.jdom2.filter.ElementFilter - Allows org.jdom2.Element
4. org.jdom2.filter.AttributeFilter - Allows org.jdom2.Attribute
5. org.jdom2.filter.Filters - Factory class to create other filters. Most users will use this class to create filters. The most important methods of this class are :
   • public static final Filter<Attribute> attribute() - matches Attribute
   • public static final Filter<Attribute> attribute(String name) - matches Attribute with a specific name.
   • public static final Filter<Attribute> attribute(String name, Namespace ns) - matches Attribute with a specific name in a specific namespace.
   • public static final Filter<Attribute> attribute(Namespace ns) - matches Attribute within a specified namespace.
   • public static final Filter<Comment> comment() - matches Comment.
   • public static final Filter<CDATA> cdata() - matches CDATA.
   • public static final Filter<DocType> doctype() - matches DocType.
   • public static final Filter<EntityRef> entityref() - matches EntityRef.
   • public static final Filter<Element> element() - matches Element.
   • public static final Filter<Document> document() - matches Document.
   • public static final Filter<Element> element(String name) - matches Element with a specified name.
   • public static final Filter<Element> element(String name, Namespace ns) - matches Element with a specified name and namespace.
   • public static final Filter<Element> element(Namespace ns) - .matches all Elements within a specified namespace
   • public static final Filter<ProcessingInstruction> processinginstruction() - matches Processing Instruction.
   • public static final Filter<Text> text() - matches Text (including CDATA).
   • public static final Filter<Text> textOnly() - matches Text (exclusing CDATA).
   • public static final Filter<Boolean> fboolean() - matches Boolean data.
   • public static final Filter<String> fstring() - matches String data.
   • public static final Filter<Double> fdouble() - matches Double data.
   • public static final <F> Filter<F> fclass(Class<F> clazz) - matches a specified class.
   • public static final Filter<Object> fpassthrough() - matches everything, does not filterFd.

The following operations can be performed on a filter

• public Filter<? extends Object> negate() - returns Objects NOT matched by the filter.
• public Filter<? extends Object> or(Filter<?> filter) - returns Objects that are passed by any one of the filters
• public Filter<T> and(Filter<?> filter) - returns objects matched by both the filters.
• public <R> Filter<R> refine(Filter<R> filter) - Similar to the ‘and‘ filter but the generic type of the result is taken from the generic type of the input

The class diagram
Lets look at an example

JDOM2 handles namespaces very well. However, there are three areas where confusion may arise while using namespaces. In this tutorial we look at them.

Creating new elements

While creating new elements in JDOM2, it is possible to pass the namespace to which the element should belong. However, the namespace only applies to the Element and not its children. i.e. the namespace assignment does not cascade. Here‘s an example

The output is Notice how the namespace prefix is applied only to only child.

Searching for a child which is in a namespace

In the next example we read the XML created in the example above. (test.xml) we then search for a child named ‘child1‘, first without specifying a namespace and then after specifying a namespace. In the first case it is not able to find the child, in the second case it does

XPath and Namespace

JDOM2 XPath allows searching for an element with a specific Namespace. If an element is specified in a new Namespace then pass that JDOM2 Namespace object when searching for that element. If the XML defines a new default Namespace then create a new ‘dummy‘ JDOM2 Namespace object with any prefix and the default Namespace URI specified in the XML. Access elements in the XML using the prefix of the ‘dummy‘ JDOM2 Namespace object. . See example for more details. The example uses the following xml

The Example

Introduction

In the earlier tutorials we looked at how to create a JDOM2 document from SAX ,DOM and StAX. In this tutorial we learn how to output JDOM2 as XML, DOM, SAX, StAXEvent and StaxStream. Lets look at the important classes

Important Classes

• XMLOutputter - This is probably the most useful outputter. It outputs the JDOM2 document as a stream of byes that can be written to a file. In other words, to create an XML file from JDOM2 document use this class. The most useful methods is public final void output(Document doc, OutputStream out). The encoding of the writer should match the encoding of the Format object of the Outputter. The conversion can be customized by using a custom XMLOutputProcessor
• DOMOutputter - Outputs a JDOM2 document as a w3c DOM Document. It can be configured by passing in three types of objects - DOMAdapter, Format and DOMOutputProcessor. A DOMAdapter is an interface whose implementation interfaces with a DOMParser to create DOM objects. The default implementation is JAXPDOMAdapter. The DOMOutputProcessor is the main class responsible for the conversion. The important method is public final void output(Document doc, XMLStreamWriter out) throws XMLStreamException. An Element can also be passed instead of a Document
• SAXOutputter - Outputs a JDOM2 document as a stream of SAX2 Events. It takes in a ContentHandler to process the SAX events. It can also be configured using an ErrorHandler, DTDHandler, EntityResolver, LexicalHandler and DeclHandler. It also uses a SAXOutputProcessor that does the bulk of the processing. The most useful constructor is public SAXOutputter(ContentHandler contentHandler) and the the output method is public final void output(Document doc, XMLStreamWriter out) throws XMLStreamException
• StAXEventOutputter Outputs the JDOM2 document as a series of events that can be read by an XMLEventConsumer. The default processor to process the conversion is DefaultStAXEventProcessor. This can be customized, if required. The most useful method is public final void output(Document doc, XMLEventConsumer out) throws XMLStreamExceptionThe format can also be specified. The following formats are available :
  • for pretty printing - Format.getPrettyFormat()
  • for whitespace-normalized output - Format.getCompactFormat()
  • for unmodified-format output - Format.getRawFormat()
• StAXStreamOutputter - Outputs the JDOM2 document as a stream that is handled by XMLStreamWriter. Here‘s how the main method looks public final void output(Element element, XMLStreamWriter out) throws XMLStreamException. The default processor is DefaultStAXStreamProcessor
• StAXStreamReader - Outputs the JDOM2 document as an XMLStreamReader.

Example

Now lets see the outputters in action

JDOM2 has classes that perform XSL transformation of the JDOM2 document. The input to the transformation is the JDOM2 document and an XML stylesheet and the output is whatever transformation the stylesheet specifies. In the example below we look at JDOM2 to do HTML transformation. By default, JDOM2 uses the JAXP TrAX classes for transformation. The important classes are :

• JDOMSource - This class holds the input for the transformation. It can be a Document, node or list of nodes.
• JDOMResult - This class holds the result of the transformation. It is generally a list of nodes or a JDOM2 document. The result tree may not be a well formed XML document.
• XSLTranfomer - The class that wraps the transformation. It uses the JAXP TrAX classes for actual transformation. The javax.xml.transform.TransformerFactory java system property determines which XSLT engine is to be used. As specified in the code documentation this could be
  • Saxon 6.x: com.icl.saxon.TransformerFactoryImpl
  • Saxon 7.x: net.sf.saxon.TransformerFactoryImpl
  • Xalan: org.apache.xalan.processor.TransformerFactoryImpl
  • jd.xslt: jd.xml.xslt.trax.TransformerFactoryImpl
  • Oracle: oracle.xml.jaxp.JXSAXTransformerFactory

Lets look at an example of a transformation.The source XML can be downloaded from here and the xsl can be downloaded from here.

Xpath is a query language specification that is used to query an XML path. It provides a language that helps in retrieving specific nodes of an XML document using a query syntax. This tutorial does not explain XPath and assumes that the user is aware of XPath. What we explain here is how to use Xpath to query a JDOM2 document. The default implementation for JDOM2 is jaxen. To run the below examples jaxen needs to be in the classpath. To query the JDOM2 document first compile an XPathExpression using an XPathFactory. Use the expression to then evaluate the JDOM2 document.