| As a Java-centric alternative to SAX and DOM, JDOM was developed. JDOM was designed with the following philosophy (taken from www.jdom.org): JDOM should be straightforward for Java programmers JDOM should support easy and efficient document modification JDOM should hide the complexities of XML wherever possible, while remaining true to the XML specification JDOM should integrate with DOM and SAX JDOM should be lightweight and fast JDOM should solve 80% (or more) of Java/XML problems with 20% (or less) of the effort
After using JDOM for the last 18+ months I have to say I think the JDOM programmers have met these requirements. Being Java programmers, we are very familiar with using Java's Collections API. All throughout Java's class libraries and components the underlying data structures are all members of Java's collections API. Because of this intimate familiarity it is only natural that we should deal with XML data similarly. The creators of JDOM understood this and, thus, created a collections API-based representation of XML data. JDOM uses the SAX parser that yields the best performance when reading documents and uses far less memory-representing data than the DOM because of the difference between the DOM overhead and the Collections API overhead. Because JDOM does hold all the XML data in memory, it is not ideal for all purposes; in some business-to-business XML transactions the sheer amount of data requires that you use SAX to avoid keeping all the data in memory. The core functionality of the JDOM API is provided in three packages, each with a distinct purpose: org.jdom: Classes to manage and create XML documents org.jdom.input: Classes to read XML documents org.jdom.output: Classes to write XML documents
Reading an XML Document The first step in reading an XML document using JDOM is parsing the document. JDOM provides the org.jdom.input.SAXBuilder class to parse XML documents. Table 25.12. org.jdom.input.SAXBuilder Constructors| Constructor | Description |
|---|
| SAXBuilder() | Creates a new SAXBuilder that will attempt to first locate a parser via JAXP, then will try to use a set of default SAX Drivers. | | SAXBuilder(boolean validate) | Creates a new SAXBuilder that will attempt to first locate a parser via JAXP, then will try to use a set of default SAX Drivers. | | SAXBuilder(java.lang.String saxDriverClass) | Creates a new SAXBuilder using the specified SAX parser. | | SAXBuilder(java.lang.String saxDriverClass, boolean validate) | Creates a new SAXBuilder using the specified SAX parser. |
Table 25.12 shows two variations of constructors: one that does not validate and one that gives to you the option to validate. If you have a SAX parser that you want to use you can specify it; otherwise, one is provided for you. Table 25.13 shows some of more useful methods of the SAXBuilder class. Table 25.13. org.jdom.input.SAXBuilder Methods| Method | Description |
|---|
| Document build(java.io.File file) | This builds a document from the supplied filename. | | Document build(org.xml.sax.InputSource in) | This builds a document from the supplied input source. | | Document build(java.io.InputStream in) | This builds a document from the supplied input stream. | | Document build(java.io.InputStream in, java.lang.String systemId) | This builds a document from the supplied input stream. | | Document build(java.io.Reader characterStream) | This builds a document from the supplied Reader. | | Document build(java.io.Reader characterStream, java.lang. String SystemId) | This builds a document from the supplied Reader. | | Document build(java.lang.String systemId) | This builds a document from the supplied URI. | | Document build(java.net.URL url) | This builds a document from the supplied URL. | | void setValidation(boolean validate) | This sets validation for the builder. |
From Table 25.13 you can see that the SAXBuilder class has a plethora of build() methods that can build an XML document from almost any source. The class also provides a setValidation() method that enables you to modify the validation mode. The build() method returns an org.jdom.Document instance. The Document class represents the XML document; its constructors are shown in Table 25.14, and its methods are shown in Table 25.15. Table 25.14. org.jdom.Document Constructors| Constructor | Description |
|---|
| Document() | Creates a new empty document. | | Document(Element rootElement) | This will create a new Document, with the supplied Element as the root element, and no DocType declaration. | | Document(Element rootElement, DocType docType) | This will create a new Document, with the supplied Element as the root element and the supplied DocType declaration. | | Document(java.util.List content) | This will create a new Document, with the supplied list of content, and no DocType declaration. | | Document(java.util.List newContent, DocType docType) | This will create a new Document, with the supplied list of content, and the supplied DocType declaration. |
Table 25.15. org.jdom.Document Methods| Method | Description |
|---|
| DocType getDocType() | This will return the DocType declaration for this Document, or null if none exists. | | Element getRootElement() | This will return the root Element for this Document. | | boolean hasRootElement() | This will return true if this document has a root element, false otherwise. | | Document setContent(java.util.List newContent) | This sets the content of the Document. | | Document setDocType(DocType docType) | This will set the DocType declaration for this Document. | | Document setRootElement(Element rootElement) | This sets the root Element for the Document. |
The Document constructors in Table 25.14 enable you to create a new XML document from an org.jdom.Element object, and its methods in Table 25.15 enable you to modify the Document and obtain the Element. The org.jdom.Element object is the core of the JDOM API; its constructors are shown in Table 25.16, and its methods are shown in Table 25.17. Table 25.16. org.jdom.Element Constructors| Constructor | Description |
|---|
| Element(java.lang.String name) | This will create an Element in no Namespace. | | Element(java.lang.String name, Namespace namespace) | This will create a new Element with the supplied (local) name, and define the Namespace to be used. | | Element(java.lang.String name, java.lang.String uri) | This will create a new Element with the supplied (local) name, and specifies the URI of the Namespace the Element should be in, resulting it being unprefixed (in the default namespace). | | Element(java.lang.String name, java.lang.String prefix, java.lang.String uri) | This will create a new Element with the supplied (local) name, and specifies the prefix and URI of the Namespace the Element should be in. |
Table 25.17. org.jdom.Element Methods| Method | Description |
|---|
| Attribute getAttribute(String name) | This returns the attribute for this element with the given name or null if no such attribute exists. | | java.util.List getAttributes() | This returns the complete set of attributes for this element, as a List of Attribute objects in no particular order, or an empty list if there are none. | | String getAttributeValue(String name) | This returns the attribute value for the attribute with the given name, null if there is no such attribute, and the empty string if the attribute value is empty. | | Element getChild(String name) | This returns the first child element within this element with the given local name | | java.util.List getChildren() | This returns a List of all the child elements nested directly (one level deep) within this element, as Element objects. | | java.util.List getChildren(String name) | This returns a List of all the child elements nested directly (one level deep) within this element with the given local name returned as Element objects. | | String getChildText(String name) | This convenience method returns the textual content of the named child element, or returns an empty String ("") if the child has no textual content. | | String getChildTextTrim(String name) | This convenience method returns the trimmed textual content of the named child element, or returns null if there's no such child. | | java.util.List getContent() | This returns the full content of the element as a List that might contain objects of type Text, Element, Comment, ProcessingInstruction, CDATA, and EntityRef. | | Document getDocument() | This retrieves the owning Document for this Element, or null if not currently a member of a Document. | | String getText() | This returns the textual content directly held under this element. | | String getTextTrim() | This returns the textual content of this element with all surrounding whitespace removed. | | boolean hasChildren() | Test whether this element has a child element. | | boolean isRootElement() | This returns a Boolean value indicating whether this Element is a root Element for a JDOM Document. | | boolean removeAttribute (Attribute attribute) | This removes the supplied Attribute should it exist. | | boolean removeAttribute(String name) | This removes the attribute with the given name | | boolean removeChild(String name) | This removes the first child element (one level deep) with the given local name | | boolean removeChildren() | This removes all child elements. | | boolean removeChildren(String name) | This removes all child elements (one level deep) with the given local name | | Element setAttribute (Attribute attribute) | This sets an attribute value for this element. | | Element setAttribute (String name, String value) | This sets an attribute value for this element. | | Element setAttributes (java.util.List newAttributes) | This sets the attributes of the element. | | Element setName(String name) | This sets the (local) name of the element. | | Element setText(String text) | This sets the content of the element to be the text given. |
The main components of XML nodes are Node name Node attributes Node text Node children
From Table 25.17 you can modify any of these values. Pay particular attention to the use of Collections classes, such as the List returned by getChildren(). Refer to www.jdom.org for more detailed information. To summarize the steps in reading an XML document: -
Create a parser. -
Parse the document and obtain a Document object. -
Get the root Element of the Document by calling the getRootElement method. -
Use the Element methods to read through the document.
In code that is SAXBuilder builder = new SAXBuilder(); Document doc = builder.build( "book.xml" ); Element root = doc.getRootElement(); List books = root.getChildren( "book" ); for( Iterator i=books.iterator(); i.hasNext(); ) { Element book = ( Element )i.next(); System.out.println( "Book: " + book.getAttributeValue( "category" ) + ", " + book.getChildTextTrim( "title" ) + ", " + book.getChildTextTrim( "author" ) + ", " + book.getChildTextTrim( "price" ) ); } This code snippet reads through the book.xml file and displays all its books. JDOM Example The following example shows how to open an XML document, parse it, display its contents to the screen, modify its contents, and then display the complete XML document. See Listing 25.11. Listing 25.11 JDOMTest.java import org.jdom.*; import org.jdom.input.*; import org.jdom.output.*; import java.util.*; import java.io.*; public class JDOMTest { public static void showBooks( Element root ) { List books = root.getChildren( "book" ); for( Iterator i=books.iterator(); i.hasNext(); ) { Element book = ( Element )i.next(); System.out.println( "Book: " + book.getAttributeValue( "category" ) + ", " + book.getChildTextTrim( "title" ) + ", " + book.getChildTextTrim( "author" ) + ", " + book.getChildTextTrim( "price" ) ); } } public static void main( String[] args ) { try { SAXBuilder builder = new SAXBuilder(); Document doc = builder.build( "book.xml" ); Element root = doc.getRootElement(); System.out.println( "Book List Before: " ); showBooks( root ); // Add a new book Element newBook = new Element( "book" ); newBook.setAttribute( "category", "fiction" ); Element newTitle = new Element( "title" ); newTitle.addContent( "Desecration" ); Element newAuthor = new Element( "author" ); newAuthor.addContent( "Tim LaHaye" ); Element newPrice = new Element( "price" ); newPrice.addContent( "19.95" ); newBook.addContent( newTitle ); newBook.addContent( newAuthor ); newBook.addContent( newPrice ); root.addContent( newBook ); System.out.println( "Book List After: " ); showBooks( root ); XMLOutputter out = new XMLOutputter( " ", true ); out.output( root, System.out ); } catch( Exception e ) { e.printStackTrace(); } } } Listing 25.11 shows the code for the JDOMTest.java class. It uses the SAXBuilder class to open the book.xml file, parse it, get a Document, and the get the root of the document. Next the program calls the showBooks() method that traverses through the contents of the root Element and displays all book elements. It then creates a new book Element and adds it to the root element by calling the addContent() method. After a subsequent call to showBooks(), it displays the contents of the XML file using the org.jdom.output.XMLOutputter class. This class has various output() methods that write out a JDOM object to an OutputStream or Writer. Table 25.18 shows the constructors for the XMLOutputter class and Table 25.19 shows some of its useful methods. Table 25.18. org.jdom.output.XMLOutputter Constructors| Constructor | Description |
|---|
| XMLOutputter() | This will create an XMLOutputter with no additional whitespace (indent or newlines) added; the whitespace from the element text content is fully preserved. | | XMLOutputter(java.lang.String indent) | This will create an XMLOutputter with the given indent added, but no new lines added; all whitespace from the element text content is included as well. | | XMLOutputter(java.lang.String indent, boolean newlines) | This will create an XMLOutputter with the given indent that prints newlines only if newlines is true; all whitespace from the element text content is included as well. | | XMLOutputter(java.lang.String indent, boolean newlines, java.lang.String encoding) | This will create an XMLOutputter with the given indent and new lines printing only if newlines is true, and encoding format encoding. | | XMLOutputter(XMLOutputter that) | This will create an XMLOutputter with all the options as set in the given XMLOutputter. |
Table 25.19. org.jdom.Element Methods| Method | Description |
|---|
| void output(Document doc, java.io.OutputStream out) | This will print the Document to the given output stream. | | void output(Document doc, java.io.Writer out) | This will print the Document to the given Writer. | | void output(Element element, java.io.OutputStream out) | Print out an Element, including its Attributes, and all contained (child) elements, and so on. | | void output(Element element, java.io.Writer out) | Print out an Element, including its Attributes, and all contained (child) elements, and so on. |
This section gave a good overview and introduction to using JDOM, but I would strongly encourage you to download it from the Web site and try using it in your own projects. |
