JDOM 1.0 (Beta 7) (Java & XML, 2nd Edition)

A.4. JDOM 1.0 (Beta 7)

JDOM 1.0 (beta 7), detailed in Chapter 7, "JDOM" and Chapter 8, "Advanced JDOM", provides a complete view of an XML document within a tree model. Although this model is similar to DOM, it is not as rigid a representation; this allows the content of an Element, for example, to be set directly, instead of setting the value of the child of that Element. Additionally, JDOM provides concrete classes rather than interfaces, allowing instantiation of objects directly rather than through the use of a factory. SAX and DOM are only used in JDOM for the construction of a JDOM Document object from existing XML data, and are detailed in the org.jdom.input package.

A.4.1. Package: org.jdom

This package contains the core classes for JDOM 1.0 [31]. These consist of XML objects modeled in Java and a set of Exceptions that can be thrown when errors occur.[32]

[31]Please note that while the JDOM API is fairly stable, it is still in beta. Minor changes may occur after the publication of this book. Please consult http://www.jdom.org for the latest JDOM classes.

[32]To avoid complete boredom in this section, I've left out all the JDOM exceptions aside from the core one, JDOMException. I'd rather focus on the classes rather than the odd exceptional condition.

A.4.1.1. Attribute

Attribute defines behavior for an XML attribute, modeled in Java. Methods allow the user to obtain the value of the attribute as well as namespace information about the attribute. An instance can be created with the name of the attribute and its value, or the Namespace and local name, as well as the value, of the attribute. Several convenience methods are also provided for automatic data conversion of the attribute's value.

public class Attribute {
    public Attribute(String name, String value);
    public Attribute(String name, String value, Namespace ns);

    public Element getParent( );
    public String getName( );
    public Namespace getNamespace( );
    public void setNamespace(Namespace ns);
    public String getQualifiedName( );
    public String getNamespacePrefix( );
    public String getNamespaceURI( );
    public String getValue( );
    public void setValue(String value);

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );

    // Convenience Methods for Data Conversion
    public String get StringValue(String default Value);
    public int getIntValue( ) throws DataConversionException;
    public long getLongValue( ) throws DataConversionException;
    public float getFloatValue( ) throws DataConversionException;
    public double getDoubleValue( ) throws DataConversionException;
    public boolean getBooleanValue( ) throws DataConversionException;
}

A.4.1.2. CDATA

The CDATA class defines behavior for XML CDATA sections.

public class CDATA {
    public CDATA(String text);

    public String getText( );
 
    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );   
}

A.4.1.3. Comment

Comment is a simple representation of an XML comment, and contains the text within the XML comment.

public class Comment {
    public Comment(String text);

    public Document getDocument( );
    public Element getParent( );
    public String getText( );
    public void setText(String text);

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.1.4. DocType

DocType represents a DOCTYPE declaration within an XML document. It includes information about the element name being constrained, as well as the public ID and system ID of the external DTD reference, if one is present.

public class DocType {
    public DocType(String elementName, String publicID, String systemID);
    public DocType(String elementName, String systemID);
    public DocType(String elementName);

    public Document getDocument( );
    public String getElementName( );
    public String getPublicID( );
    public DocType setPublicID(String publicID);
    public String getSystemID( );
    public DocType setSystemID(String systemID);

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.1.5. Document

Document models an XML document in Java. Document requires that it be created with a root Element, although that Element can be replaced with setRootElement( ). The getContent( ) method returns all the content of the Document, which includes the root Element and any Comments that may exist at the document level in the XML document.

public class Document {
    public Document(Element rootElement, DocType docType);
    public Document(Element rootElement);
    public Document(List content);
    public Document(List content, DocType docType);

    public Document addContent(Comment comment);
    public Document removeContent(Comment comment);
    public Document addContent(ProcessingInstruction pi);
    public Document removeContent(ProcessingInstruction pi);
    public Element getRootElement( ) throws NoSuchElementException;
    public Document setRootElement(Element rootElement);
    public DocType getDocType( );
    public Document setDocType(DocType docType);
    public List getContent( );
    public void setMixedContent(List content);

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.1.6. Element

Element is a Java representation of an XML element. It is completely namespace-aware, so all methods take in a single element name as an argument, as well as optional namespace information. The result of calls to getText( ) is always a String, either the textual content of the XML element or an empty String. An Element is considered to have mixed content when it has a combination of textual data and nested elements, as well as optional comments, entities, and processing instructions. This complete List of content can be obtained with getContent( ), and the results in the List evaluated through instanceof against a String, Element, or Comment.

The addXXX( ) methods are designed to be chained together, and therefore return the modified Element:

Element element = new Element("root");
element.addChild(new Element("child")
    .addChild(new Element("grandchild")
        .addAttribute("name", "value")
        .setContent("Hello World!"))
    .addChild(new Element("anotherChild"))
);

This would result in the following XML document fragment:

<root>
  <child>
    <grandchild name="value">
      Hello World!
    </grandchild>
  </child>
  <anotherChild />
</root>

Here's the API listing:

public class Element {
    public Element(String name);
    public Element(String name, String uri);
    public Element(String name, String prefix, String uri);
    public Element(String name, Namespace ns);

    public Document getDocument( );
    public Element getParent( );
    public Element detach( );
    public String getName( );
    public void setName(String name);
    public Namespace getNamespace( );
    public Namespace getNamespace(String prefix);
    public void setNamespace(Namespace ns);
    public String getNamespacePrefix( );
    public String getNamespaceURI( );
    public String getQualifiedName( );
    public void addNamespaceDeclaration(Namespace additionalNS);
    public void removeNamespaceDeclaration(Namespace additionalNS);
    public List getAdditionalNamespaces( );

    public List getContent( );
    public Element setMixedContent(List mixedContent);
    public Element addContent(CDATA cdata);
    public Element addContent(Comment comment);
    public Element addContent(Element element);
    public Element addContent(EntityRef entityRef);
    public Element addContent(ProcessingInstruction pi);
    public Element addContent(String text);
    public boolean removeContent(CDATA cdata);
    public boolean removeContent(Comment comment);
    public boolean removeContent(Element element);
    public boolean removeContent(EntityRef entityRef);
    public boolean removeContent(ProcessingInstruction pi);

    public boolean hasChildren( );
    public Element getChild(String name);
    public Element getChild(String name, Namespace ns);
    public List getChildren( );
    public List getChildren(String name);
    public List getChildren(String name, Namespace ns);
    public boolean removeChild(String name);
    public boolean removeChild(String name, Namespace ns);
    public boolean removeChildren( );
    public boolean removeChildren(String name);
    public boolean removeChildren(String name, Namespace ns);
    public Element setChildren(List children);

    public Attribute getAttribute(String name);
    public Attribute getAttribute(String name, Namespace ns);
    public List getAttributes( );
    public String getAttributeValue(String name);
    public String getAttributeValue(String name, Namespace ns);
    public boolean removeAttribute(String name);
    public boolean removeAttribute(String name, Namespace ns);
    public Element setAttribute(Attribute attribute);
    public Element setAttributes(List attributes);

    public String getChildText(String name);
    public String getChildText(String name, Namespace ns);
    public String getChildTextTrim(String name);
    public String getChildTextTrim(String name, Namespace ns);
    public String getText( );
    public String getTextNormalize( );
    public String getTextTrim( );
    public Element setText(String text);

    public boolean isRootElement( );

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.1.7. EntityRef

This class defines a JDOM model for entity references in XML documents. It allows for setting and accessing of the reference's name, public ID, and system ID.

public class EntityRef {
    public EntityRef(String name);
    public EntityRef(String name, String publicID, String systemID);

    public Document getDocument( );
    public Element getParent( );
    public String getName( );
    public EntityRef setName(String name);
    public String getPublicID( );
    public void setPublicID(String publicID);
    public String getSystemID( );
    public void setSystemID(String systemID);
    public EntityRef detach( );

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.1.8. JDOMException

This is the core JDOM Exception that other JDOM Exception classes subclass. It provides for error messages as well as the wrapping of a root cause Exception, in the case that a JDOMException needs to wrap a lower-level Exception.

public class JDOMException extends Exception {
    public JDOMException( );
    public JDOMException(String message);
    public JDOMException(String message, Throwable rootCause);

    public Throwable getCause( );
    public String getMessage( );
}

A.4.1.9. Namespace

The Namespace class handles namespace mappings used in JDOM objects.

public class Namespace {
    public static Namespace getNamespace(String uri);
    public static Namespace getNamespace(String prefix, String uri);

    public String getPrefix( );
    public String getURI( );

    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.1.10. ProcessingInstruction

ProcessingInstruction defines behavior for an XML processing instruction, modeled in Java. It allows specific handling for the target as well as the raw data for the target. Additionally, as many PIs use data in the form of name-value pairs (much like attributes), this allows retrieval and addition of name-value pairs. For example, in the <?cocoon-process type="xslt"?> processing instruction, invoking getValue("type") on the ProcessingInstruction representing that XML PI would return "xslt".

public class ProcessingInstruction {
    public ProcessingInstruction(String target, Map data);
    public ProcessingInstruction(String target, String data);

    public ProcessingInstruction detach( );
    public Document getDocument( );
    public Element getParent( );
    public String getTarget( );
    public String getData( );
    public ProcessingInstruction setData(String data);
    public ProcessingInstruction setData(Map data);
    public String getValue(String name);
    public ProcessingInstruction setValue(String name, String value);
    public boolean removeValue(String name);

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.1.11. Text

This class represents character data "owned" by a JDOM Element. It is generally invisible to the user, as the Element class converts this class to a simple String when the value is requested. It is only exposed through an Element's getContent( ) method.

public class Text {
    public Text(String stringValue);

    public Element getParent( );
    public void append(String stringValue);
    public String getValue( );
    public void setValue(String stringValue);

    public Object clone( );
    public boolean equals(Object obj);
    public int hashCode( );
    public String toString( );
}

A.4.2. Package: org.jdom.adapters

This package contains adapters that allow a standard interface for obtaining a DOM Document object from any DOM parser (including DOM Level 1 parsers). Adapters can be easily added for any parser that desires to have JDOM support.

A.4.2.1. AbstractDOMAdapter

This class provides default behavior for the version of getDocument( ) that takes in a filename by wrapping the file in a FileOutputStream and delegating invocation to getDocument(InputStream).

public abstract class AbstractDOMAdapter implements DOMAdapter {
    public abstract Document getDocument(InputStream in, boolean validate) 
        throws IOException;
    public abstract Document getDocument(File filename, boolean validate) 
        throws IOException;
    public abstract Document createDocument(DocType docType) 
        throws IOException;
}

A.4.2.2. DOMAdapter

This class defines the interface that adapters must implement. This includes a means to produce a DOM Document from a filename or an InputStream, as well as a means of obtaining a new, empty DOM Document object.

public interface DOMAdapter {
    public abstract Document getDocument(InputStream in, boolean validate) 
        throws IOException;
    public abstract Document getDocument(File filename, boolean validate) 
        throws IOException;
    public abstract Document createDocument(DocType docType) 
        throws IOException;
}

Specific adapter classes are not detailed here, as additions and modifications may be made during publication of the book. As of this writing, functional adapters are provided for the following parsers:

Oracle Version 1 XML Parser
Oracle Version 2 XML Parser
Sun Project X Parser
Sun/Apache Crimson Parser
Apache Xerces Parser
IBM XML4J Parser

A.4.3. Package: org.jdom.input

This package defines the classes for building a JDOM Document object from various input sources, such as SAX streams and existing DOM trees. It also provides an interface for using customized versions of the JDOM classes, like user-defined subclasses of Element and Attribute.

A.4.3.1. BuilderErrorHandler

This is the default error handler used for JDOM document construction.

public class BuilderErrorHandler 
    implements org.xml.sax.ErrorHandler {

    public void warning(SAXParserException exception);
    public void error(SAXParserException exception);
    public void fatalError(SAXParserException exception);
}

A.4.3.2. DOMBuilder

This class provides the ability to create a JDOM Document object from an XML input source using a parser that supports DOM, the Document Object Model. It uses the various adapters in org.jdom.adapters, so if a parser is requested for which there is no adapter, errors occur. Additionally, a method is provided for building a JDOM Document object from an existing DOM tree (org.w3c.dom.Document). When the DOMBuilder is constructed, validation can be requested, as can the class name of the adapter to use. If neither is supplied, the default behavior occurs: no validation takes place and the Apache Xerces parser is used.

You can also set the factory to use (see the JDOMFactory entry) for generating JDOM classes in the build process.

public class DOMBuilder {
    public DOMBuilder(String adapterClass, boolean validate);
    public DOMBuilder(String adapterClass);
    public DOMBuilder(boolean validate);
    public DOMBuilder( );

    public Document build(InputStream in);
    public Document build(File file);
    public Document build(URL url);
    public Document build(org.w3c.dom.Document domDocument);
    public Element build(org.w3c.dom.Element domElement);

    public void setValidation(boolean validate);
    public void setFactory(JDOMFactory factory);
}

A.4.3.3. JDOMFactory

This interface allows users to provide their own factories that produce JDOM constructs (Element, Attribute, etc.). When a factory implementation is passed to a builder using the setFactory( ) method, this is used for creating new JDOM constructs. It allows complete customization of the JDOM object creation process.

For the sake of brevity and clarity, I'm not going to include the very extensive list of methods available to this factory, but instead refer you to the Javadoc. Every possible construction of every JDOM class is included in this class, and all these methods return the type of object being constructed.

A.4.3.4. SAXBuilder

This class provides the ability to create a JDOM Document object from an XML input source using a parser that supports SAX, the Simple API for XML. It can use any SAX parser implementation that is SAX 2.0-compliant. When the SAXBuilder is constructed, validation can be requested, as well as the class name of the SAX driver to use. If neither is supplied, the default behavior occurs: no validation takes place and the Apache Xerces parser is used.

You can also set the factory to use (see the JDOMFactory entry) for generating JDOM classes in the build process.

public class SAXBuilder {
    public SAXBuilder(String saxDriverClass, boolean validate);
    public SAXBuilder(String saxDriverClass);
    public SAXBuilder(boolean validate);
    public SAXBuilder( );

    public Document build(InputStream in);
    public Document build(InputStream in, String systemID);
    public Document build(InputSource inputSource);
    public Document build(Reader characterStream);
    public Document build(Reader characterStream, String systemID);
    public Document build(File file);
    public Document build(URL url);
    public Document build(org.w3c.dom.Document domDocument);
    public Element build(org.w3c.dom.Element domElement);

    public void setDTDHandler(DTDHandler dtdHandler);
    public void setEntityResolver(EntityResolver entityResolver);
    public void setErrorHandler(ErrorHandler errorHandler);
    public void setExpandEntities(boolean expandEntities);
    public void setXMLFilter(XMLFilter xmlFilter);
    public void setIgnoringElementContentWhitespace(boolean ignore);
    public void setValidation(boolean validate);
    public void setFactory(JDOMFactory factory);
}

A.4.4. Package: org.jdom.output

This package defines behavior for output of JDOM Document objects. Of particular note is the SAXOutputter class, which allows a JDOM Document to fire SAX events off to an application expecting SAX behavior, and DOMOutputter, which converts from JDOM to DOM structures. And, of course, XMLOutputter is by far the most common output class for JDOM objects. Like some of the classes in the org.jdom.input package, these three classes have, literally, hundreds of methods between them. Rather than fill ten pages with this rather boring information, I'll again refer you to the Javadoc online at http://www.jdom.org. That will have the most current options for using any of the JDOM outputter classes.