Processing XML with Javaв„ў: A Guide to SAX, DOM, JDOM, JAXP, and TrAX

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