DOM Level 2 (Java & XML, 2nd Edition)

A.2.1. Package: org.w3c.dom

This package contains the core interfaces and classes for DOM Level 2. Typically a vendor's parsing software provides an implementation of those interfaces that are implicitly used by your application software.

A.2.1.1. Attr

This interface represents an XML attribute (on an element) within Java. It provides access to the name and value of the attribute, and allows the setting of the value (for mutability).[29] The getSpecified( ) method indicates if the attribute (and its value) was explicitly noted in the XML document, or if a value was not specified but the document's DTD assigned a default value to the attribute. Finally, the "owning" element can be obtained from this interface.

[29]In this and other setXXX( ) methods in DOM, a DOMException results when a modification is attempted on a node that is read-only.

public interface Attr extends Node {
    public String getName( );
    public boolean getSpecified( );
    public String getValue( );
    public void setValue(String value) throws DOMException;
    public Element getOwnerElement( );
}

A.2.1.2. CDATASection

This interface does not define any methods of its own; instead it inherits all of the Text interface's methods. However, by having its own interface (and thus its own node type), a distinction can be drawn between text within XML CDATA sections and simple text (not in a CDATA section) within an element.

public interface CDATASection extends Text {
}

A.2.1.3. CharacterData

This interface is the "super" interface for all textual Node types in DOM (Text, Comment, and indirectly CDATASection). It defines methods for accessing and setting the data within a textual node, as well as a set of methods for dealing with the textual data directly as characters: obtaining the length, appending, inserting, and deleting data, and replacing all or part of the data. All of these methods throw DOMExceptions when the node is read-only.

public interface CharacterData extends Node {
    public String getData( ) throws DOMException;
    public void setData(String data) throws DOMException;
    public int getLength( );
    public String substringData(int offset, int count)
        throws DOMException;
    public void appendData(String arg) throws DOMException;
    public void insertData(int offset, String arg) throws DOMException;
    public void deleteData(int offset, int count) throws DOMException;
    public void replaceData(int offset, int count, String arg)
        throws DOMException;
}

A.2.1.4. Comment

This interface provides a Java representation for an XML comment. Similar to CDATASection, it adds no methods of its own but does allow a distinction (based on the type of the interface) to distinguish between text and comments in an XML document.

public interface Comment extends CharacterData {
}

A.2.1.5. Document

This interface is the DOM representation of a complete XML document. It is also the key for creating new XML elements, attributes, PIs, and other constructs. In addition to allowing retrieval of the DTD declaration (getDocType( )) and root element (getDocumentElement( )), this allows searching through the tree in a pre-order fashion for a specific element (getElementsByTagName( )). Because the DOM model requires that all Node implementations be tied to a DOM Document object, this provides methods for creating the various types of DOM Nodes. Each createXXX( ) method has a complement that supports namespaces through createXXXNS( ). Additionally, Nodes can be imported into this Document through importNode( ); the boolean value indicates if the children of the imported Node should be recursively imported as well.

public interface Document extends Node {
    public DocumentType getDoctype( );
    public DOMImplementation getImplementation( );
    public Element getDocumentElement( );
    public Element createElement(String tagName) throws DOMException;
    public DocumentFragment createDocumentFragment( );
    public Text createTextNode(String data);
    public Comment createComment(String data);
    public CDATASection createCDATASection(String data)
        throws DOMException;
    public ProcessingInstruction 
        createProcessingInstruction(String target, String data)
        throws DOMException;
    public Attr createAttribute(String name) throws DOMException;
    public EntityReference createEntityReference(String name)
        throws DOMException;
    public NodeList getElementsByTagName(String tagname);
    public Node importNode(Node importedNode, boolean deep)
        throws DOMException;
    public Element createElementNS(String namespaceURI, 
                                   String qualifiedName)
        throws DOMException;
    public Attr createAttributeNS(String namespaceURI, 
                                  String qualifiedName)
        throws DOMException;
    public NodeList getElementsByTagNameNS(String namespaceURI, 
                                           String localName);
    public Element getElementById(String elementId);
}

A.2.1.6. DocumentFragment

This interface provides for dealing with only a portion of a complete Document object at one time. It is useful for manipulating portions of a DOM tree without having to store the entire tree in memory.

public interface DocumentFragment extends Node {
}

A.2.1.7. DocumentType

This interface represents an XML document's DOCTYPE declaration. The name is the element name immediately following <!DOCTYPE, and the system ID and public ID of any referenced DTD are available as well. Additionally, if any inline entities or notations are present, they can be obtained through the appropriate getXXX( ) methods.

public interface DocumentType extends Node {
    public String getName( );
    public NamedNodeMap getEntities( );
    public NamedNodeMap getNotations( );
    public String getPublicId( );
    public String getSystemId( );
    public String getInternalSubset( );
}

A.2.1.8. DOMException

This class provides an Exception for DOM interfaces to throw when problems occur. It also provides a set of error codes that represent the various problems that occur using DOM and might result in the Exception being thrown.

public class DOMException extends RuntimeException {
       public DOMException(short code, String message);

    // Exception codes
    public static final short INDEX_SIZE_ERR;
    public static final short DOMSTRING_SIZE_ERR;
    public static final short HIERARCHY_REQUEST_ERR;
    public static final short WRONG_DOCUMENT_ERR;
    public static final short INVALID_CHARACTER_ERR;
    public static final short NO_DATA_ALLOWED_ERR;
    public static final short NO_MODIFICATION_ALLOWED_ERR;
    public static final short NOT_FOUND_ERR;
    public static final short NOT_SUPPORTED_ERR;
    public static final short INUSE_ATTRIBUTE_ERR;
    public static final short INVALID_STATE_ERR; 
    public static final short SYNTAX_ERR; 
    public static final short INVALID_MODIFICATION_ERR; 
    public static final short NAMESPACE_ERR; 
    public static final short INVALID_ACCESS_ERR;
}

A.2.1.9. DOMImplementation

This interface attempts to provide a standard entry point for accessing vendor- specific DOM implementations, and allowing the creation of a DocumentType and Document within those vendor implementations.[30] It also provides a method (hasFeature( )) for querying the implementation for a specific feature support, like the DOM Level 2 Traversal or Range modules.

[30]Unfortunately, to obtain an instance of a DOMImplementation, you must have a Document object and use getDOMImplementation( ), or directly load the vendor's classes. This tends to result in a chicken-and-egg scenario; see Chapter 5, "DOM" and Chapter 6, "Advanced DOM" for more details.

public interface DOMImplementation {
    public boolean hasFeature(String feature, String version);
    public DocumentType createDocumentType(String qualifiedName, 
                                           String publicId, 
                                           String systemId)
        throws DOMException;
    public Document createDocument(String namespaceURI, 
                                   String qualifiedName, 
                                   DocumentType doctype)
        throws DOMException;
}

A.2.1.10. Element

This interface provides a Java representation of an XML element. It provides methods to get its name and attributes, as well as to set these values. It also supplies several flavors of access to the XML attributes, including namespace-aware versions of the getXXX( ) and setXXX( ) methods.

public interface Element extends Node {
    public String getTagName( );
    public String getAttribute(String name);
    public void setAttribute(String name, String value)
        throws DOMException;
    public void removeAttribute(String name) throws DOMException;
    public Attr getAttributeNode(String name);
    public Attr setAttributeNode(Attr newAttr) throws DOMException;
    public Attr removeAttributeNode(Attr oldAttr) throws DOMException;
    public NodeList getElementsByTagName(String name);
    public String getAttributeNS(String namespaceURI, String localName);
    public void setAttributeNS(String namespaceURI, String qualifiedName, 
                               String value)
        throws DOMException;
    public void removeAttributeNS(String namespaceURI, String localName)
                                  throws DOMException;
    public Attr getAttributeNodeNS(String namespaceURI, String localName);
    public Attr setAttributeNodeNS(Attr newAttr) throws DOMException;
    public NodeList getElementsByTagNameNS(String namespaceURI, 
                                           String localName);
    public boolean hasAttribute(String name);
    public boolean hasAttributeNS(String namespaceURI, String localName);
}

A.2.1.11. Entity

This provides a Java representation of an entity (parsed or unparsed) in an XML document. Access to the system ID and public ID as well as the notation for the entity (from the DTD) is provided through accessor methods.

public interface Entity extends Node {
    public String getPublicId( );
    public String getSystemId( );
    public String getNotationName( );
}

A.2.1.12. EntityReference

This interface represents the resulting value from an entity reference once the entity has been resolved. This interface assumes that character and predefined entity references have already occurred when this interface is exposed to the application client.

public interface EntityReference extends Node {
}

A.2.1.13. NamedNodeMap

This interface defines a list, much like NodeList, but requires that each Node in the list be a named Node (such as an Element or Attr). Because of this requirement, methods can be provided to access members of the list by their names (with or without namespace support). The list also provides for removal and modification of its members. These methods all throw DOMExceptions when the referenced Node is read-only.

public interface NamedNodeMap {
    public Node getNamedItem(String name);
    public Node setNamedItem(Node arg) throws DOMException;
    public Node removeNamedItem(String name) throws DOMException;
    public Node item(int index);
    public int getLength( );
    public Node getNamedItemNS(String namespaceURI, String localName);
    public Node setNamedItemNS(Node arg) throws DOMException;
    public Node removeNamedItemNS(String namespaceURI, String localName)
        throws DOMException;
}

A.2.1.14. Node

This is the central interface for all DOM objects. It provides a robust set of methods for accessing information about a Node in the DOM tree. It also allows for handling of a Node's children (if they exist). While most of the methods are self-explanatory, there are several methods worth noting: getAttributes( ) only returns non-null data if the Node is an Element; cloneNode( ) provides for a shallow or deep copy of a Node; normalize( ) moves all text into non-adjacent Text nodes (no two Text nodes are adjacent, and all resolved textual entity references are consolidated into Text nodes); and isSupported( ) provides information about the feature set of the Node. Namespace-aware methods are also provided (getNamespaceURI( ), getPrefix( ), and getLocalName( )). Finally, a set of constants is provided for identifying the type of a Node by comparing the constants against the result of getNodeType( ).

public interface Node {
    public String getNodeName( );
    public String getNodeValue( ) throws DOMException;
    public void setNodeValue(String nodeValue) throws DOMException;
    public short getNodeType( );
    public Node getParentNode( );
    public NodeList getChildNodes( );
    public Node getFirstChild( );
    public Node getLastChild( );
    public Node getPreviousSibling( );
    public Node getNextSibling( );
    public NamedNodeMap getAttributes( );
    public Document getOwnerDocument( );
    public Node insertBefore(Node newChild,  Node refChild)
        throws DOMException;
    public Node replaceChild(Node newChild, Node oldChild)
                             throws DOMException;
    public Node removeChild(Node oldChild) throws DOMException;
    public Node appendChild(Node newChild) throws DOMException;
    public boolean hasChildNodes( );
    public Node cloneNode(boolean deep);
    public void normalize( );
    public boolean isSupported(String feature, String version);
    public String getNamespaceURI( );
    public String getPrefix( );
    public void setPrefix(String prefix) throws DOMException;
    public String getLocalName( );
    public boolean hasAttributes( );

    // Node Type Constants
    public static final short ELEMENT_NODE;
    public static final short ATTRIBUTE_NODE;
    public static final short TEXT_NODE;
    public static final short CDATA_SECTION_NODE;
    public static final short ENTITY_REFERENCE_NODE;
    public static final short ENTITY_NODE;
    public static final short PROCESSING_INSTRUCTION_NODE;
    public static final short COMMENT_NODE;
    public static final short DOCUMENT_NODE;
    public static final short DOCUMENT_TYPE_NODE;
    public static final short DOCUMENT_FRAGMENT_NODE;
    public static final short NOTATION_NODE;
}

A.2.1.15. NodeList

This interface is a DOM structure analogous to a Java Vector or List. It is the return value of any method that supports multiple Node implementations as a result. This allows iteration through the items as well as providing the ability to get a Node at a specific index.

public interface NodeList {
    public Node item(int index);
    public int getLength( );
}

A.2.1.16. Notation

This interface represents a NOTATION construct in a DTD, used to declare the format of an unparsed entity or for declaration of PIs. This provides access to both the system ID and public ID within the declaration. Both return null if they are not present.

public interface Notation extends Node {
    public String getPublicId( );
    public String getSystemId( );
}

A.2.1.17. ProcessingInstruction

This interface represents an XML processing instruction (PI). It provides methods for getting the target and the data of the PI. Note that there is no means of accessing the "name/value" pairs within the PI individually. The data can also be set for the PI.

public interface ProcessingInstruction extends Node {
    public String getTarget( );
    public String getData( );
    public void setData(String data) throws DOMException;
}

A.2.1.18. Text

This interface provides a Java representation of an XML element's textual data. The only method it adds to those defined in CharacterData is one that will split the node into two nodes. The original Text node contains text up to the specified offset, and the method returns a new Text node with the text after the offset. Like other mutability methods, a DOMException is thrown when the node is read-only.

public interface Text extends CharacterData {
    public Text splitText(int offset) throws DOMException;
}

A.2. DOM Level 2