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 prefix, String uri, String value);
    public Attribute(String name, Namespace ns, String value);
    public String getName(  );
    public String getQualifiedName(  );
    public String getNamespacePrefix(  );
    public String getNamespaceURI();
    public String getValue(  );
    public void setValue(String value);

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

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 String getText(  );
    public void setText(String text);
    public String toString(  );
}

This Exception is thrown when a conversion from an Attribute’s or Element’s value to a specified data type occurs. The message that results specifies the name of the Attribute whose value was requested as well as the data type to which conversion is requested. It is provided as a subclass of JDOMException so that an application using JDOM can catch that single Exception and receive all error notifications.

public class DataConversionException extends JDOMException {
	public DataConversionException(String name, String dataType);
}

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 String getElementName(  );
    public String getPublicID(  );
    public DocType setPublicID(String publicID);
    public String getSystemID(  );
    public DocType setSystemID(String systemID);
}

Document models an XML Document in Java. It requires that it be created with a root Element, although that Element can be replaced with setRootElement( ). It also allows the setting of a DocType and a List of ProcessingInstructions, and the retrieval of those same objects. Convenience methods are provided to allow inline addition of PIs to the Document. 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 Element getRootElement(  ) throws NoSuchElementException;
    public Document setRootElement(Element rootElement);
    public DocType getDocType(  );
    public Document setDocType(DocType docType);
    public List getProcessingInstructions(  );
    public List getProcessingInstructions(String target);
    public ProcessingInstruction getProcessingInstruction(String target)
        throws NoSuchProcessingInstructionException;
    public Document addProcessingInstruction(ProcessingInstruction pi);
    public Document addProcessingInstruction(String target, String data);
    public Document addProcessingInstruction(String target, Map data);
    public Document setProcessingInstructions(
        List processingInstructions);
    public boolean removeProcessingInstruction(
        ProcessingInstruction processingInstruction);
    public boolean removeProcessingInstruction(String target);
    public boolean removeProcessingInstructions(String target);
    public Document addComment(Comment comment);
    public List getMixedContent(  );
}

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 getContent( ) 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 getMixedContent( ), 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>

There are also convenience methods to allow inline adding of Attributes to an Element, through setAttribute(String name, String value). The removal methods work in the same fashion, and provide namespace-aware versions as well.

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 String getName(  );
    public String getNamespacePrefix(  );
    public String getNamespaceURI();
    public String getQualifiedName(  );
    public String getContent(  );
    public Element setContent(String textContent);
    public boolean hasMixedContent(  );
    public List getMixedContent(  );
    public Element setMixedContent(List mixedContent);
    public List getChildren(  );
    public Element setChildren(List children);
    public List getChildren(String name);
    public List getChildren(String name, Namespace ns);
    public Element getChild(String name) throws NoSuchElementException;
    public Element getChild(String name, Namespace ns) 
        throws NoSuchElementException;
    public Element addChild(Element element);
    public Element addChild(ProcessingInstruction pi);
    public Element addChild(Comment comment);
    public Element addChild(String s);
    public boolean removeChild(Element element);
    public boolean removeChild(Comment comment);
    public boolean removeChild(String name);
    public boolean removeChild(String name, Namespace ns);
    public boolean removeChildren(String name);
    public boolean removeChildren(String name, Namespace ns);
    public boolean removeChildren(  );
    public List getAttributes(  );
    public Attribute getAttribute(String name) 
        throws NoSuchAttributeException;
    public Attribute getAttribute(String name, Namespace ns) 
        throws NoSuchAttributeException;
    public Element setAttributes(List attributes);
    public Element addAttribute(Attribute attribute);
    public Element addAttribute(String name, String value);
    public Element addAttribute(String name, Namespace ns, String value);
    public void removeAttribute(String name);
    public void removeAttribute(String name, Namespace ns);
}

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

The Namespace class handles namespace mappings used in JDOM Document 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 isDefault();
}

This Exception is thrown when a specific Attribute is searched for and not found. The message that results contains the name of the Attribute that was searched upon.

public class NoSuchAttributeException extends JDOMException {
	public NoSuchAttributeException(String attributeName);
}

This Exception is thrown when a specific Element is searched for and not found. The message that results contains the name of the Element that was searched upon.

public class NoSuchElementException extends JDOMException {
	public NoSuchElementException(String elementName);
}

This Exception is thrown when a specific ProcessingInstruction is searched for and not found. The message that results contains the target of the ProcessingInstruction that was searched upon.

public class NoSuchProcessingInstructionException extends JDOMException {
	public NoSuchProcessingInstructionException(String target)
}

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

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 Document getDocument(String filename, boolean validate) 
        throws IOException;
    public abstract Document getDocument(InputStream in,boolean validate) 
        throws IOException;
    public abstract Document createDocument(  ) throws IOException;
}

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 Document getDocument(String filename, boolean validate) 
        throws IOException;
    public Document getDocument(InputStream in, boolean validate) 
        throws IOException;
    public Document createDocument(  ) 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:

This base implementation of Builder provides routing for the build( ) methods that take in a File or URL, and convert them to streams to pass to the build( ) method that takes in an InputStream.

public abstract class AbstractBuilder implements Builder {
    public abstract Document build(InputStream in) throws JDOMException;
    public Document build(File file) throws JDOMException;
    public Document build(URL url) throws JDOMException;
}

This base interface defines behavior for all Document builders. Each Builder implementation must provide a mechanism to create a JDOM Document object from an InputStream, File, or URL. All throw JDOMExceptions, which will hold information about well-formedness or validity errors (when appropriate) if errors in Document building occur.

public interface Builder {
    public Document build(InputStream in) throws JDOMException;
    public Document build(File file) throws JDOMException;
    public Document build(URL url) throws JDOMException;
}

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

public class DOMBuilder extends AbstractBuilder {
    public DOMBuilder(String adapterClass, boolean validate);
    public DOMBuilder(String adapterClass);
    public DOMBuilder(boolean validate);
    public DOMBuilder(  );
    public Document build(InputStream in) throws JDOMException;
    public Document build(org.w3c.dom.Document domDocument);
}

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.^[23] 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.

public class SAXBuilder extends AbstractBuilder {
    public SAXBuilder(String saxDriverClass, boolean validate);
    public SAXBuilder(String saxDriverClass);
    public SAXBuilder(boolean validate);
    public SAXBuilder(  );
    public Document build(InputStream in) throws JDOMException;
}

This class handles output of a Document to a supplied OutputStream in XML format. Various constructors are provided for setting the level of indention that should occur, as well as determining if new line feeds should be added to the output. The default behavior is “pretty-printing,” which uses two spaces for each indention level and outputs new line feeds. Once the instance is created, the output( ) method will output the supplied Document to the specified OutputStream.

public class XMLOutputter {
    public XMLOutputter(  );
    public XMLOutputter(String indent);
    public XMLOutputter(String indent, boolean newlines);
    public void output(Document doc, OutputStream out)
        throws IOException;
}