JDOM Quick Reference

JDOM is an open source, pure Java API for reading, writing, and manipulating XML documents. This section provides complete signatures for the documented, public parts of JDOM, with the single exception of the org.jdom.adapters package, which is really intended only for internal use in JDOM.

Caution

JDOM is not finished at the time of this writing. This appendix is based on an early development release of JDOM beta 9, current as of May 17, 2002. I expect some of the details here to change before JDOM is released. (In fact, I’m actively lobbying for a few of them to change.)

org.jdom

The org.jdom package contains the core classes that JDOM uses to model the XML tree, one class per node type, as well as some generically useful classes such as Verifier, JDOMFactory, and JDOMException.

Attribute

The Attribute class represents an attribute node. Each attribute has a local name, a namespace (which may be null), a string value, a type, and a parent Element. Attribute types are represented by the named int constants in this class.

package org.jdom;

public class Attribute implements Serializable, Cloneable {

  public static final int UNDECLARED_ATTRIBUTE;
  public static final int CDATA_ATTRIBUTE;
  public static final int ID_ATTRIBUTE;
  public static final int IDREF_ATTRIBUTE;
  public static final int IDREFS_ATTRIBUTE;
  public static final int ENTITY_ATTRIBUTE;
  public static final int ENTITIES_ATTRIBUTE;
  public static final int NMTOKEN_ATTRIBUTE;
  public static final int NMTOKENS_ATTRIBUTE;
  public static final int NOTATION_ATTRIBUTE;
  public static final int ENUMERATED_ATTRIBUTE;
  
  protected String    name;
  protected Namespace namespace;
  protected String    value;
  protected int       type;
  protected Object    parent;

  protected Attribute();
  public    Attribute(
   String name, String value, Namespace namespace)
   throws IllegalNameException, IllegalDataException;
  public    Attribute(
   String name, String value, int type, Namespace namespace)
   throws IllegalNameException, IllegalDataException;
  public    Attribute(String name, String value)
   throws IllegalNameException, IllegalDataException;
  public    Attribute(String name, String value, int type)
   throws IllegalNameException, IllegalDataException;

  public    Element   getParent();
  protected Attribute setParent(Element parent);
  public    Document  getDocument();
  public    Attribute detach();
  public    String    getName();
  public    Attribute setName(String name) 
   throws IllegalNameException;
  public    String    getQualifiedName();
  public    String    getNamespacePrefix();
  public    String    getNamespaceURI();
  public    Namespace getNamespace();
  public    Attribute setNamespace(Namespace namespace)
   throws IllegalNameException;
  public    String    getValue();
  public    Attribute setValue(String value);
  public    int       getAttributeType();
  public    Attribute setAttributeType(int type) 
   throws IllegalDataException;
  
  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();

  // Convenience methods for converting the value to various
  // primitive types
  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;

 }

CDATA

The CDATA class is a subclass of Text (from which it inherits most of its functionality) that represents a CDATA section. The only real difference between this class and Text is that an XMLOutputter will use a CDATA section to write out the contents of a CDATA object rather than escaping characters like < with entity and character references.

package org.jdom;

public class CDATA extends Text {

  protected CDATA();
  public    CDATA(String s);

  public Text setText(String s) throws IllegalDataException;
  public void append(String s) throws IllegalDataException;
  
  public String toString();

 }

Comment

The Comment class represents a comment node. Each Comment object contains the text of the comment, a parent Element (which will be null if this comment is in the prolog or epilog), and an owner Document.

package org.jdom;

public class Comment implements Serializable, Cloneable {

  protected String text;
  protected Object parent;

  protected Comment();
  public    Comment(String text) throws IllegalDataException;

  public    Element  getParent();
  protected Comment  setParent(Element parent);
  public    Comment  detach();
  public    Document getDocument();
  protected Comment  setDocument(Document document);
  public    String   getText();
  public    Comment  setText(String text)
   throws IllegalDataException;

  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();

 }

DocType

The DocType class represents a document type declaration. Each DocType object contains the declared root element name, the public ID and the system ID (both of which may be null), the owner document, and a String containing the internal DTD subset.

package org.jdom;

public class DocType implements Serializable, Cloneable {

  protected String   elementName;
  protected String   publicID;
  protected String   systemID;
  protected Document document;
  protected String   internalSubset;

  protected DocType();
  public    DocType(String elementName, String publicID, 
   String systemID)
   throws IllegalNameException, IllegalDataException;
  public    DocType(String elementName, String systemID) throws IllegalNameException;
  public    DocType(String elementName) 
   throws IllegalNameException;

  public    String   getElementName();
  public    DocType  setElementName(String elementName) 
   throws IllegalNameException;
  public    String   getPublicID();
  public    DocType  setPublicID(String publicID) 
   throws IllegalDataException;;
  public    String   getSystemID();
  public    DocType  setSystemID(String url);
  public    Document getDocument();
  protected DocType  setDocument(Document document);
  public    void     setInternalSubset(String declarations);
  public    String   getInternalSubset();

  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();

 }

Document

The Document class represents a complete document and serves as the root of the JDOM tree. Each Document object contains a list of its content and the document’s DocType (if it has one). Each Document should have exactly one Element in its content list. However, documents may be temporarily rootless. Almost anything you do to such a Document other than setting the root element will throw an IllegalStateException.

package org.jdom;

public class Document implements Serializable, Cloneable {

  protected ContentList content;
  protected DocType     docType;

  public Document();
  public Document(Element rootElement, DocType docType) 
   throws IllegalAddException;
  public Document(Element rootElement);
  public Document(List newContent, DocType docType) 
   throws IllegalAddException;
  public Document(List content) throws IllegalAddException;

  public boolean  hasRootElement();
  public Element  getRootElement() throws IllegalStateException;
  public Document setRootElement(Element rootElement);
  public Element  detachRootElement();
  public DocType  getDocType();
  public Document setDocType(DocType docType) 
   throws IllegalAddException;
  public Document addContent(ProcessingInstruction pi);
  public Document addContent(Comment comment);
  public List     getContent();
  public List     getContent(Filter filter);
  public Document setContent(List newContent) 
   throws IllegalAddException;
  public boolean  removeContent(ProcessingInstruction pi);
  public boolean  removeContent(Comment comment);

  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();

 }

Element

The Element class represents a complete element. Each element has a local name, a namespace (which may be null), a parent Element (which is null if this is the root element or not currently part of a document), a list of its children, a list of its attributes, and a list of any namespace prefixes declared on the element that are not used by the element or one of its attributes.

package org.jdom;

public class Element implements Serializable, Cloneable {

  protected String        name;
  protected Namespace     namespace;
  protected List          additionalNamespaces;
  protected Object        parent;
  protected AttributeList attributes;
  protected ContentList   content;

  protected Element();
  public    Element(String name, Namespace namespace) 
   throws IllegalNameException;
  public    Element(String name) throws IllegalNameException;
  public    Element(String name, String uri) 
   throws IllegalNameException;
  public    Element(String name, String prefix, String uri) 
   throws IllegalNameException;

  public    String    getName();
  public    Element   setName(String name) 
   throws IllegalNameException;
  public    Namespace getNamespace();
  public    Element   setNamespace(Namespace namespace);
  public    String    getNamespacePrefix();
  public    String    getNamespaceURI();
  public    Namespace getNamespace(String prefix);
  public    String    getQualifiedName();
  public    void      addNamespaceDeclaration(
   Namespace additional);
  public    void      removeNamespaceDeclaration(
   Namespace additionalNamespace);
  public    List      getAdditionalNamespaces();

  public    Element   getParent();
  protected Element   setParent(Element parent);
  public    Element   detach();
  public    boolean   isRootElement();
  protected Element   setDocument(Document document);
  public    Document  getDocument();
  public    boolean   isAncestor(Element element);

  public    String    getText();
  public    Element   setText(String text);
  public    String    getTextTrim();
  public    String    getTextNormalize();

  public    String    getChildText(String name);
  public    String    getChildTextTrim(String name);
  public    String    getChildTextNormalize(String name);
  public    String    getChildText(String name, Namespace ns);
  public    String    getChildTextTrim(String name, 
   Namespace namespace);
  public    String    getChildTextNormalize(String name, 
   Namespace namespace);

  public    List      getContent();
  public    List      getContent(Filter filter);
  public    Element   setContent(List newContent) 
   throws IllegalAddException;
  public    List      getChildren();
  public    List      getChildren(String name);
  public    List      getChildren(String name, Namespace ns);
  public    Element   getChild(String name, Namespace ns);
  public    Element   getChild(String name);
  public    Element   addContent(String s) 
   throws IllegalAddException;
  public    Element   addContent(Text text) 
   throws IllegalAddException;
  public    Element   addContent(Element element) 
   throws IllegalAddException;
  public    Element   addContent(ProcessingInstruction pi)
   throws IllegalAddException;
  public    Element   addContent(EntityRef ref) 
   throws IllegalAddException;
  public    Element   addContent(Comment comment)
   throws IllegalAddException;
  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   removeContent(Element element);
  public    boolean   removeContent(ProcessingInstruction pi);
  public    boolean   removeContent(Comment comment);
  public    boolean   removeContent(Text text);
  public    boolean   removeContent(EntityRef entity);

  // Attribute methods
  public    List      getAttributes();
  public    Attribute getAttribute(String name);
  public    Attribute getAttribute(String name, Namespace ns);
  public    String    getAttributeValue(String name);
  public    String    getAttributeValue(String name, 
   Namespace ns, String def);
  public    String    getAttributeValue(String name, String def);
  public    String    getAttributeValue(String name, Namespace ns);
  public    Element   setAttributes(List newAttributes) 
   throws IllegalAddException;
  public    Element   setAttribute(String name, String value) 
   throws IllegalNameException, IllegalDataException;
  public    Element   setAttribute(String name, String value, Namespace ns) 
   throws IllegalNameException, IllegalDataException;
  public    Element   setAttribute(Attribute attribute);
  public    boolean   removeAttribute(String name);
  public    boolean   removeAttribute(String name, Namespace ns);
  public    boolean   removeAttribute(Attribute attribute);

  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();

 }

EntityRef

The EntityRef class represents an unexpanded entity reference, such as might be produced by a non-validating parser which does not read the external DTD subset. Entity references for which the replacement text is known are not included as EntityRef objects. Instead their replacement text is parsed and included.

package org.jdom;

public class EntityRef implements Serializable, Cloneable {

  protected String name;
  protected String publicID;
  protected String systemID;
  protected Object parent;

  protected EntityRef();
  public    EntityRef(String name);
  public    EntityRef(String name, String systemID);
  public    EntityRef(String name, String publicID, 
   String systemID);

  public    String    getName();
  public    EntityRef setName(String name) 
   throws IllegalNameException;
  public    String    getPublicID();
  public    String    getSystemID();
  public    EntityRef setPublicID(String newPublicID) 
   throws IllegalDataException;
  public    EntityRef setSystemID(String url) 
   throws IllegalDataException;
  public    Document  getDocument();
  public    Element   getParent();
  public    EntityRef detach();
  protected EntityRef setParent(Element parent);

  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();  
  
 }

Namespace

The Namespace class encapsulates a namespace URI and possibly a prefix. It uses the flyweight design pattern so that twenty different elements in the same namespace share only one Namespace object between them.

package org.jdom;

public final class Namespace  {

  // empty string
  public static final Namespace NO_NAMESPACE;  
  
  // http://www.w3.org/XML/1998/namespace
  public static final Namespace XML_NAMESPACE; 
  
  // The constructor is private
  
  // Factory methods
  public static Namespace getNamespace(String prefix, String uri) 
   throws IllegalNameException;
  public static Namespace getNamespace(String uri) 
   throws IllegalNameException;

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

  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();

 }

ProcessingInstruction

The ProcessingInstruction class represents a complete processing instruction. Each ProcessingInstruction has a target, data, a parent Element (which will be null if this instruction is in the prolog or epilog), and an owner Document. If the data is stored in pseudo-attributes, then there’s also a map containing the pseudo-attributes separated into names and values. However, not all processing instructions can be represented in this format.

package org.jdom;

public class ProcessingInstruction 
 implements Serializable, Cloneable {

  protected String target;
  protected String rawData;
  protected Map    mapData;
  protected Object parent;

  protected ProcessingInstruction();
  public    ProcessingInstruction(String target, Map data) 
   throws IllegalTargetException;
  public    ProcessingInstruction(String target, String data) 
   throws IllegalTargetException;

  public    ProcessingInstruction setTarget(String newTarget) 
   throws IllegalTargetException;
  public    String                getTarget();
  public    Element               getParent();
  protected ProcessingInstruction setParent(Element parent);
  public    ProcessingInstruction detach();
  public    Document              getDocument();
  protected ProcessingInstruction setDocument(Document document);
  public    String                getData();
  public    ProcessingInstruction setData(String data);

  public    ProcessingInstruction setData(Map data);
  public    List                  getNames();
  public    String                getValue(String name);
  public    ProcessingInstruction setValue(String name, 
   String value);
  public    boolean               removeValue(String name);

  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();  

 }

Text

The Text class represents a text node. In general, Text objects are not guaranteed to contain the maximum possible contiguous run of text, though this will be true of documents that have been created by a SAXBuilder and not modified since. In most normal usage you can ignore this class and use strings instead.

package org.jdom;

public class Text implements Serializable, Cloneable {

  protected String value;
  protected Object parent;

  protected Text();
  public    Text(String s) throws IllegalDataException;

  public String   getText();
  public String   getTextTrim();
  public String   getTextNormalize();
  public Text     setText(String s) throws IllegalDataException;
  public void     append(String s) throws IllegalDataException;
  public void     append(Text text) throws IllegalDataException;

  public Element  getParent();
  public Document getDocument();
  protected Text  setParent(Element parent);
  public Text     detach();

  public static String normalizeString(String s);
  
  // Java utility methods
  public       String  toString();
  public final boolean equals(Object o);
  public final int     hashCode();
  public       Object  clone();  

 }

Verifier

Verifier is a utility class the other JDOM classes rely on to decide whether or not particular strings are acceptable for particular purposes. For example, TimeLimit is a legal element name but Time Limit is not. You don’t normally need to use this class directly. If you do, you should note that the various check methods all return null if the argument passes the test and a non-empty string containing an error message if the test fails.

package org.jdom;

public final class Verifier  {

  public static String checkElementName(String name);
  public static String checkAttributeName(String name);
  public static String checkCharacterData(String text);
  public static String checkCDATASection(String data);
  public static String checkNamespacePrefix(String prefix);
  public static String checkNamespaceURI(String uri);
  public static String checkNamespaceCollision(
   Namespace namespace, Namespace other);
  public static String checkNamespaceCollision(
   Attribute attribute, Element element);
  public static String checkNamespaceCollision(
   Namespace namespace, Element element);
  public static String checkNamespaceCollision(
   Namespace namespace, Attribute attribute);
  public static String checkNamespaceCollision(
   Namespace namespace, List list);
  public static String checkProcessingInstructionTarget(
   String target);
  public static String checkCommentData(String data);
  public static String checkPublicID(String publicID);
  public static String checkSystemLiteral(String systemID);  
  public static String checkXMLName(String name);
  
  public static boolean isXMLCharacter(char c);
  public static boolean isXMLNameCharacter(char c);
  public static boolean isXMLNameStartCharacter(char c);
  public static boolean isXMLLetterOrDigit(char c);
  public static boolean isXMLLetter(char c);
  public static boolean isXMLCombiningChar(char c);
  public static boolean isXMLExtender(char c);
  public static boolean isXMLDigit(char c);

 }

Exceptions and Errors

JDOM defines a number of unique exceptions. JDOMException is the basic superclass for most checked exceptions JDOM methods can throw. A few methods in the input and output packages also throw standard IOExceptions. Finally, JDOM provides several subclasses of IllegalArgumentException (a runtime exception) that are thrown when a program attempts to set XML constructs like element names to illegal values.

DataConversionException

DataConversionException is thrown by the five getInt/Long/Float/Double/BooleanValue() methods in Attribute when the attribute value cannot be parsed as the requested type. This is a checked exception.

package org.jdom;

public class DataConversionException extends JDOMException {

  public DataConversionException(String message, String type);

 }
IllegalAddException

IllegalAddException is thrown when code attempts to add a node where it doesn’t belong. This could be because the new child already has a parent or because the new child can never be placed where you’re trying to fit it (e.g. adding Text object as a child of a Document). This is a runtime exception.

package org.jdom;

public class IllegalAddException 
 extends IllegalArgumentException {

  public IllegalAddException(Element base, Attribute added, 
   String reason);
  public IllegalAddException(Element base, Element added, 
   String reason);
  public IllegalAddException(Document base, Element added, 
   String reason);
  public IllegalAddException(Element base, 
   ProcessingInstruction added, String reason);
  public IllegalAddException(Document base, 
   ProcessingInstruction added, String reason);
  public IllegalAddException(Element base, Comment added, 
   String reason);
  public IllegalAddException(Element base, CDATA added, 
   String reason);
  public IllegalAddException(Element base, Text added, 
   String reason);
  public IllegalAddException(Document base, Comment added, 
   String reason);
  public IllegalAddException(Element base, EntityRef added, 
   String reason);
  public IllegalAddException(Element base, Namespace added, 
   String reason);
  public IllegalAddException(Document base, DocType added, 
   String reason);
  public IllegalAddException(String reason);

 }
IllegalDataException

An IllegalDataException is thrown when code attempts to set some text content to a string that does not satisfy XML’s well-formedness rules. Exactly what these rules are depends on context. For instance, a comment cannot contain the two hyphen string --. No content can include the ASCII vertical tab or bell characters, and so forth. The data argument contains the illegal text. This is a runtime exception.

package org.jdom;

public class IllegalDataException 
 extends IllegalArgumentException {

  public IllegalDataException(String data, String construct, 
   String reason);
  public IllegalDataException(String data, String construct);

 }
IllegalNameException

An IllegalNameException is thrown when code attempts to set the name of an attribute, element, or entity reference to a string that is not a namespace well-formed XML name. This is a runtime exception.

package org.jdom;

public class IllegalNameException 
 extends IllegalArgumentException {

  public IllegalNameException(String name, String construct, 
   String reason);
  public IllegalNameException(String name, String construct);

 }
IllegalTargetException

An IllegalTargetException is thrown when code attempts to set the target of a processing instruction to a string that is not a legal XML name. This is a runtime exception.

package org.jdom;

public class IllegalTargetException 
 extends IllegalArgumentException {

  public IllegalTargetException(String target, 
   String reason);
  public IllegalTargetException(String target);

 }
JDOMException

JDOMException is the common superclass for the different kinds of checked exceptions that may be thrown while working with JDOM.

package org.jdom;

public class JDOMException extends Exception {

  protected Throwable cause;

  public JDOMException();
  public JDOMException(String message);
  public JDOMException(String message, Throwable cause);

  public Throwable initCause(Throwable cause);
  public Throwable getCause();
  public String    getMessage();
  public void      printStackTrace();
  public void      printStackTrace(PrintStream out);
  public void      printStackTrace(PrintWriter out);

 }

org.jdom.filter

JDOM uses the filter package internally to make sure client code doesn’t do silly things like adding a java.io.InputStream to an Element’s children, or slightly less silly but still illegal things such as adding a Text object to a Document’s children. You can also use filters in your own code to simplify navigation and search in XML documents.

ContentFilter

ContentFilter is the basic filter that allows you to specify what kinds of nodes you want to pass the filter. The actual filter is stored as an int mask. The individual node types are integral powers of two that set exactly one bit in the mask. As usual with bit masks, you can combine the different fields with the bitwise or operator |.

package org.jdom.filter;

public class ContentFilter implements Filter {

  public static final int ELEMENT;
  public static final int CDATA;
  public static final int TEXT;
  public static final int COMMENT;
  public static final int PI;
  public static final int ENTITYREF;
  public static final int DOCUMENT;
  
  protected int filterMask;

  public ContentFilter();
  public ContentFilter(boolean allVisible);
  public ContentFilter(int mask);

  public int  getFilterMask();
  public void setFilterMask(int mask);
  public void setDefaultMask();

  public void setDocumentContent();
  public void setElementContent();
  public void setElementVisible(boolean visible);
  public void setCDATAVisible(boolean visible);
  public void setTextVisible(boolean visible);
  public void setCommentVisible(boolean visible);
  public void setPIVisible(boolean visible);
  public void setEntityRefVisible(boolean visible);

  public boolean canAdd(Object o);
  public boolean canRemove(Object o);
  public boolean matches(Object o);
  public boolean equals(Object o);

 }

ElementFilter

The ElementFilter class enables you to define filters that pass only elements with a certain name, or a certain namespace, or a certain name in a certain namespace.

Note

It is likely that the behavior of the ElementFilter(String name) constructor will be changed so that it creates a filter that selects elements with that name and no namespace rather than elements with that name in any namespace.

package org.jdom.filter;

public class ElementFilter implements Filter {

  protected String name;
  protected Namespace namespace;

  public ElementFilter();
  public ElementFilter(String name);
  public ElementFilter(Namespace namespace);
  public ElementFilter(String name, Namespace namespace);

  public boolean canAdd(Object o);
  public boolean canRemove(Object o);
  public boolean matches(Object o);
  public boolean equals(Object o);

 }

Filter

The Filter interface identifies which child nodes should appear in a JDOM list. Node objects for which matches() returns false are filtered out of the list.

Caution

The canAdd() and canRemove() methods are probably going to be deprecated and then removed in the near future.

package org.jdom.filter;
      
public interface Filter  {

  public boolean canAdd(Object o);
  public boolean canRemove(Object o);
  public boolean matches(Object o);

 }

org.jdom.input

The org.jdom.input class contains classes involved with building JDOM objects from other formats such as XML files, DOM Document objects, and such.

BuilderErrorHandler

The BuilderErrorHandler class is used to report errors that occur during SAX parsing. By default it rethrows the exception to halt parsing for errors and fatal errors and ignores warnings. You don’t normally need to interact with this class directly.

package org.jdom.input;

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


  public BuilderErrorHandler();

  public void warning(SAXParseException exception) 
   throws SAXException;
  public void error(SAXParseException exception) 
   throws SAXException;
  public void fatalError(SAXParseException exception) 
   throws SAXException;

 }

DefaultJDOMFactory

The DefaultJDOMFactory class is used by SAXBuilder and DOMBuilder to create standard, undecorated JDOM trees. You rarely need to use this class directly.

package org.jdom.input;

public class DefaultJDOMFactory implements JDOMFactory {

  public DefaultJDOMFactory();

  public Attribute             attribute(String name,
   String value, Namespace namespace) 
   throws IllegalNameException, IllegalDataException;
  public Attribute             attribute(String name, 
   String value, int type, Namespace namespace) 
   throws IllegalNameException, IllegalDataException;
  public Attribute             attribute(String name,
   String value) throws IllegalNameException, IllegalDataException;
  public Attribute             attribute(String name, 
   String value, int type) 
   throws IllegalNameException, IllegalDataException;
  public CDATA                 cdata(String text) 
   throws IllegalDataException;
  public Text                  text(String text) 
   throws IllegalDataException;
  public Comment               comment(String text) 
   throws IllegalDataException;
  public DocType               docType(String elementName, 
   String publicID, String systemID) 
   throws IllegalNameException, IllegalDataException;
  public DocType               docType(String elementName, 
   String systemID) throws IllegalNameException, IllegalDataException;
  public DocType               docType(String elementName) 
   throws IllegalNameException;
  public Document              document(Element rootElement, 
   DocType docType) IllegalAddException;
  public Document              document(Element rootElement) 
   throws IllegalAddException;
  public Element               element(String name, 
   Namespace namespace) throws IllegalNameException;
  public Element               element(String name) 
   throws IllegalNameException;
  public Element               element(String name, String uri) 
   throws IllegalNameException;
  public Element               element(String name, 
   String prefix, String uri) throws IllegalNameException;
  public ProcessingInstruction processingInstruction(
   String target, Map data) throws IllegalTargetException;
  public ProcessingInstruction processingInstruction(
   String target, String data) throws IllegalTargetException;
  public EntityRef             entityRef(String name) 
   throws IllegalNameException;
  public EntityRef             entityRef(String name, 
   String publicID, String systemID) 
   throws IllegalNameException, IllegalTargetException;

 }

DOMBuilder

The DOMBuilder class converts DOM org.w3c.dom.Document objects into org.jdom.Document objects and DOM org.w3c.dom.Element objects into org.jdom.Element objects. It’s useful for interoperating with DOM programs and libraries.

package org.jdom.input;

public class DOMBuilder  {

  public DOMBuilder();
  public DOMBuilder(String adapterClass);

  public void setFactory(JDOMFactory factory);
  
  public Document build(org.w3c.dom.Document domDocument)
   throws IllegalDataException;
  public Element  build(org.w3c.dom.Element  domElement) 
   throws IllegalDataException;

 }

JDOMFactory

DOMBuilder and SAXBuilder rely on a JDOMFactory to build node objects. You can implement this class in order to have the builder objects build subclasses of your own devising rather than the standard JDOM classes. This interface is for advanced use, and then only when subclassing the standard org.jdom classes.

package org.jdom.input;

public interface JDOMFactory  {

  public Attribute             attribute(String name, 
   String value, Namespace namespace);
  public Attribute             attribute(String name, 
   String value, int type, Namespace namespace);
  public Attribute             attribute(String name, 
   String value);
  public Attribute             attribute(String name, 
   String value, int type);
  public CDATA                 cdata(String text);
  public Text                  text(String text);
  public Comment               comment(String text);
  public DocType               docType(String elementName, 
   String publicID, String systemID);
  public DocType               docType(String elementName, 
   String systemID);
  public DocType               docType(String elementName);
  public Document              document(Element rootElement, 
   DocType docType);
  public Document              document(Element rootElement);
  public Element               element(String name, 
   Namespace namespace);
  public Element               element(String name);
  public Element               element(String name, String uri);
  public Element               element(String name,
   String prefix, String uri);
  public ProcessingInstruction processingInstruction(
   String target, Map data);
  public ProcessingInstruction processingInstruction(
   String target, String data);
  public EntityRef             entityRef(String name);
  public EntityRef             entityRef(String name, 
   String publicID, String systemID);

 }

SAXBuilder

SAXBuilder is the preferred means of parsing XML documents into JDOM. It relies on an underlying SAX parser, but is agnostic about which parser is used.

package org.jdom.input;

public class SAXBuilder  {

  protected JDOMFactory factory;

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

  public void setFactory(JDOMFactory factory);
  public void setValidation(boolean validate);
  public void setErrorHandler(ErrorHandler errorHandler);
  public void setEntityResolver(EntityResolver entityResolver);
  public void setDTDHandler(DTDHandler dtdHandler);
  public void setXMLFilter(XMLFilter xmlFilter);
  public void setIgnoringElementContentWhitespace(
   boolean ignoringWhite);
  public void setFeature(String name, boolean value);
  public void setProperty(String name, Object value);
  public void setExpandEntities(boolean expand);

  public Document build(InputSource in) 
   throws JDOMException, IOException;
  public Document build(InputStream in) 
   throws JDOMException, IOException;
  public Document build(File file) 
   throws JDOMException, IOException;
  public Document build(URL url) 
   throws JDOMException, IOException;
  public Document build(InputStream in, String systemID) 
   throws JDOMException, IOException;
  public Document build(Reader characterStream) 
   throws JDOMException, IOException;
  public Document build(Reader characterStream, String SystemID) 
   throws JDOMException, IOException;
  public Document build(String systemID) 
   throws JDOMException, IOException;

  protected SAXHandler createContentHandler();
  protected void       configureContentHandler(
   SAXHandler contentHandler);
  protected XMLReader  createParser() throws JDOMException;
  protected void       configureParser(XMLReader parser, 
   SAXHandler contentHandler) throws JDOMException;
  protected URL        fileToURL(File f) 
   throws MalformedURLException;

 }

SAXHandler

SAXBuilder uses SAXHandler to receive information from the underlying SAX parser. It’s extremely rare that you need to use this class yourself.

package org.jdom.input;

public class SAXHandler extends DefaultHandler 
 implements LexicalHandler, DeclHandler, DTDHandler {

  protected Stack      stack;
  protected boolean    atRoot;
  protected boolean    inDTD;
  protected boolean    inInternalSubset;
  protected boolean    previousCDATA;
  protected boolean    inCDATA;
  protected boolean    suppress;
  protected LinkedList declaredNamespaces;
  protected LinkedList availableNamespaces;

  public SAXHandler();
  public SAXHandler(JDOMFactory factory);

  public Document    getDocument();
  public JDOMFactory getFactory();
  public Locator     getDocumentLocator();

  public void    setExpandEntities(boolean expand);
  public boolean getExpandEntities();
  public void    setIgnoringElementContentWhitespace(
   boolean ignoringWhite);
  public boolean getIgnoringElementContentWhitespace();
  
  // DeclHandler methods
  public void    externalEntityDecl(String name, 
   String publicID, String systemID) 
   throws SAXException;
  public void    attributeDecl(String elementName, 
   String attributeName, String type, String valueDefault, String value) 
   throws SAXException;
  public void    elementDecl(String name, String model) throws SAXException;
  public void    internalEntityDecl(String name, String value) throws SAXException;

  // ContentHandler methods
  public void setDocumentLocator(Locator locator);
  public void startPrefixMapping(String prefix, String uri)
   throws SAXException;
  public void endPrefixMapping(String prefix) throws SAXException;
  public void startElement(String namespaceURI, String localName, 
   String qualifiedName, Attributes atts)
    throws SAXException;
  public void characters(char ch, int start, int length)
   throws SAXException;
  public void ignorableWhitespace(char ch, int start, int length) 
   throws SAXException;
  public void skippedEntity(String name) throws SAXException;
  public void processingInstruction(String target, String data) 
   throws SAXException;
  public void endElement(String namespaceURI, String localName, 
   String qualifiedName) throws SAXException;

  // LexicalHandler methods
  public void startDTD(String name, String publicID, String systemID) 
   throws SAXException;
  public void endDTD() throws SAXException;
  public void startEntity(String name) throws SAXException;
  public void endEntity(String name) throws SAXException;
  public void startCDATA() throws SAXException;
  public void endCDATA() throws SAXException;
  public void comment(char ch, int start, int length) 
   throws SAXException;

  // DTDHandler methods
  public void notationDecl(String name, String publicID, 
   String systemID) throws SAXException;
  public void unparsedEntityDecl(String name, String publicID, 
   String systemID, String notationName) throws SAXException;

  // Internal methods
  protected void    flushCharacters() throws SAXException;
  protected void    appendExternalId(String publicID,
   String systemID);
  protected Element getCurrentElement() throws SAXException;

 }

org.jdom.output

The org.jdom.output package is responsible for converting JDOM Document objects into other forms such as files, streams of text, DOM Document objects, and SAX event sequences.

DOMOutputter

The DOMOutputter class converts a JDOM Document object to a DOM Document object.

package org.jdom.output;

public class DOMOutputter  {

  public DOMOutputter();
  public DOMOutputter(String adapterClass);

  public org.w3c.dom.Document output(Document document) 
   throws JDOMException;

  protected org.w3c.dom.Element output(Element element, 
   org.w3c.dom.Document factory, NamespaceStack namespaces) 
   throws JDOMException;
  protected org.w3c.dom.Attr    output(Attribute attribute, 
   org.w3c.dom.Document factory) throws JDOMException;

 }

SAXOutputter

The SAXOutputter class walks a JDOM Document tree while firing events at a SAX ContentHandler.

package org.jdom.output;

public class SAXOutputter  {

  public SAXOutputter();
  public SAXOutputter(ContentHandler contentHandler);
  public SAXOutputter(ContentHandler contentHandler,
   ErrorHandler errorHandler, DTDHandler dtdHandler,
   EntityResolver entityResolver);
  public SAXOutputter(ContentHandler contentHandler, 
   ErrorHandler errorHandler, DTDHandler dtdHandler, 
   EntityResolver entityResolver, LexicalHandler lexicalHandler);

  public void           setContentHandler(
   ContentHandler contentHandler);
  public ContentHandler getContentHandler();
  public void           setErrorHandler(
   ErrorHandler errorHandler);
  public ErrorHandler   getErrorHandler();
  public void           setDTDHandler(DTDHandler dtdHandler);
  public DTDHandler     getDTDHandler();
  public void           setEntityResolver(
   EntityResolver entityResolver);
  public EntityResolver getEntityResolver();
  public void           setLexicalHandler(
   LexicalHandler lexicalHandler);
  public LexicalHandler getLexicalHandler();
  public void           setDeclHandler(DeclHandler declHandler);
  public DeclHandler    getDeclHandler();

  public void    setReportNamespaceDeclarations(
   boolean declareNamespaces);
  public void    setReportDTDEvents(boolean reportDtdEvents);
  public void    setFeature(String name, boolean value) 
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public boolean getFeature(String name) 
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public void    setProperty(String name, Object value) 
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public Object  getProperty(String name) 
   throws SAXNotRecognizedException, SAXNotSupportedException;

  public void output(Document document) throws JDOMException;

  protected XMLReader createParser() throws Exception;

 }

XMLOutputter

The XMLOutputter class writes a JDOM Document onto an OutputStream or Writer or into a String. Using an OutputStream is preferable to using a Writer because it allows JDOM to more accurately determine which characters need to be escaped.

package org.jdom.output;

public class XMLOutputter implements Cloneable {

  public XMLOutputter();
  public XMLOutputter(String indent);
  public XMLOutputter(String indent, boolean newlines);
  public XMLOutputter(String indent, boolean newlines, 
   String encoding);
  public XMLOutputter(XMLOutputter that);

  public void setLineSeparator(String separator);
  public void setNewlines(boolean newlines);
  public void setEncoding(String encoding);
  public void setOmitEncoding(boolean omitEncoding);
  public void setOmitDeclaration(boolean omitDeclaration);
  public void setExpandEmptyElements(boolean expandEmpties);
  public void setTrimAllWhite(boolean trimAllWhite);
  public void setTextTrim(boolean textTrim);
  public void setTextNormalize(boolean textNormalize);
  public void setIndent(String indent);

  public void output(Document doc, OutputStream out) 
   throws IOException;
  public void output(DocType doctype, OutputStream out) 
   throws IOException;
  public void output(Element element, OutputStream out) 
   throws IOException;
  public void outputElementContent(Element element, 
   OutputStream out) throws IOException;
  public void output(List list, OutputStream out)
   throws IOException;
  public void output(CDATA cdata, OutputStream out) 
   throws IOException;
  public void output(Text text, OutputStream out) 
   throws IOException;
  public void output(Comment comment, OutputStream out) 
   throws IOException;
  public void output(ProcessingInstruction pi, OutputStream out) 
   throws IOException;
  public void output(EntityRef entity, OutputStream out) 
   throws IOException;

  public void output(Document doc, Writer out) 
   throws IOException;
  public void output(DocType doctype, Writer out) 
   throws IOException;
  public void output(Element element, Writer out) 
   throws IOException;
  public void outputElementContent(Element element, Writer out)
   throws IOException;
  public void output(List list, Writer out) 
   throws IOException;
  public void output(CDATA cdata, Writer out) 
   throws IOException;
  public void output(Text text, Writer out) 
   throws IOException;
  public void output(Comment comment, Writer out)
   throws IOException;
  public void output(ProcessingInstruction pi, Writer out)
   throws IOException;
  public void output(EntityRef entity, Writer out) 
   throws IOException;

  public String outputString(Document doc);
  public String outputString(DocType doctype);
  public String outputString(Element element);
  public String outputString(List list);
  public String outputString(CDATA cdata);
  public String outputString(Text text);
  public String outputString(String s);
  public String outputString(Comment comment);
  public String outputString(ProcessingInstruction pi);
  public String outputString(EntityRef entity);

  public String escapeAttributeEntities(String s);
  public String escapeElementEntities(String s);

  public int parseArgs(String args, int i);

  protected Writer makeWriter(OutputStream out) 
   throws UnsupportedEncodingException;
  protected Writer makeWriter(OutputStream out, String enc) 
   throws UnsupportedEncodingException;

  protected void printDeclaration(Document doc, Writer out, 
   String encoding) throws IOException;
  protected void printDocType(DocType docType, Writer out)
   throws IOException;
  protected void printComment(Comment comment, Writer out) 
   throws IOException;
  protected void printProcessingInstruction(
   ProcessingInstruction pi, Writer out) throws IOException;
  protected void printEntityRef(EntityRef entity, Writer out) 
   throws IOException;
  protected void printCDATA(CDATA cdata, Writer out)
   throws IOException;
  protected void printText(Text text, Writer out) 
   throws IOException;
  protected void printString(String s, Writer out)
   throws IOException;
  protected void printElement(Element element, Writer out, 
   int level, 
   XMLOutputter.NamespaceStack namespaces) throws IOException;
  protected void printContentRange(List content, int start, 
   int end, Writer out, int level, XMLOutputter.NamespaceStack namespaces) throws IOException;
  protected void printTextRange(List content, int start, int end, 
   Writer out) throws IOException;
  protected void printAttributes(List attributes, Element parent, 
   Writer out, XMLOutputter.NamespaceStack namespaces) 
   throws IOException;
  protected void newline(Writer out) throws IOException;
  protected void indent(Writer out, int level) 
   throws IOException;
  
  protected XMLOutputter.NamespaceStack createNamespaceStack();

  public Object clone();
  public String toString();

 }

XMLOutputter.NamespaceStack

The inner class NamespaceStack is used by XMLOutputter to keep track of which namespaces are in scope at any given point, and thus do not need to be redeclared. You only need to use this class if you’re subclassing XMLOutputter.

package org.jdom.output;

protected class XMLOutputter.NamespaceStack 
 extends NamespaceStack {

  protected XMLOutputter.NamespaceStack();

 }

org.jdom.transform

The org.jdom.transform package allows JDOM programs to interface with TrAX-based XSLT processors by providing JDOM implementations of the TrAX Source and Result interfaces.

JDOMResult

JDOMResult can be used as an output for TrAX transformations that produce JDOM Documents.

package org.jdom.transform;

public class JDOMResult extends SAXResult {

  public static final String JDOM_FEATURE;

  public JDOMResult();

  public void        setDocument(Document document);
  public Document    getDocument();
  public void        setFactory(JDOMFactory factory);
  public JDOMFactory getFactory();
  public void        setHandler(ContentHandler handler);
  public void        setLexicalHandler(LexicalHandler handler);

 }

JDOMSource

JDOMSource can be used as an input for TrAX transformations that transform JDOM Documents.

package org.jdom.transform;

public class JDOMSource extends SAXSource {

  public static final String JDOM_FEATURE;

  public JDOMSource(Document source);

  public void      setDocument(Document source);
  public Document  getDocument();
  public void      setInputSource(InputSource inputSource) 
   throws UnsupportedOperationException;
  public void      setXMLReader(XMLReader reader) 
   throws UnsupportedOperationException;
  public XMLReader getXMLReader();

 }

org.jdom.xpath

The org.jdom.xpath package provides a simple interface to XPath evaluation for JDOM Documents. Jaxen is the underlying implementation.

XPath

The XPath class allows you to evaluate XPath expressions relative to JDOM node objects.

package org.jdom.xpath;

public abstract class XPath implements Serializable {

  protected XPath(String expr) throws JDOMException;

  public static XPath newInstance(String path)
   throws JDOMException;

  public List   selectNodes(Object context) 
   throws JDOMException;
  public Object selectSingleNode(Object context) 
   throws JDOMException;
  public String valueOf(Object context) throws JDOMException;
  public Number numberValueOf(Object context) 
   throws JDOMException;
  public void   setVariable(String name, Object value) 
   throws IllegalArgumentException;
  public String getXPath();

  public static List   selectNodes(Object context, String path) 
   throws JDOMException;
  public static Object selectSingleNode(Object context, 
   String path) throws JDOMException;

 }

Copyright 2001, 2002 Elliotte Rusty Haroldelharo@metalab.unc.eduLast Modified June 04, 2002
Up To Cafe con Leche