home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book HomeJava and XML, 2nd EditionSearch this book

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


Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.