JDOM

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.

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 and JDOMException .

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 changes.)

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 such as the less-than sign 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 nonvalidating parser that 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. Not all processing instructions can be represented in this format, however.

 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, although this will be true of documents created by a SAXBuilder and not modified since. In common 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 will seldom need to use this class directly. If you do, then note that all of the various check methods return null if the argument passes the test and a nonempty 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 that JDOM methods can throw. A few methods in the input and output packages also throw standard IOException s. Finally, JDOM provides several subclasses of IllegalArgumentException (a runtime exception) that are thrown when a program attempts to set XML constructs such as 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 (for example, 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 well- formedness rules. Exactly what these rules are depends on context. For example, 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 ensure that client code doesn't do silly things such as 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 to create 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 the child nodes that should appear in a JDOM list. Node objects for which matches() returns false are filtered out of the list.

 package org.jdom.filter;  public interface  Filter  {   public boolean  canAdd  (Object  o  );   public boolean  canRemove  (Object  o  );   public boolean  matches  (Object  o  );  } 

Caution

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

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 reports errors that occur during SAX parsing. By default it rethrows the exception to halt parsing for errors and fatal errors and ignores warnings. You seldom 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 when 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 it 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 enables JDOM programs to interface with TrAX-based XSLT processors by providing JDOM implementations of the TrAX Source and Result interfaces.

JDOMResult

JDOMResult is useful as an output for TrAX transformations that produce JDOM Document s.

 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 is useful as an input for TrAX transformations that transform JDOM Document s.

 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 for XPath evaluation of JDOM Document s. 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;  }