Documents

An entire XML document is represented by a special type of node. An important concept to appreciate at this point is that the root element of an XML document is not the root node of the DOM. If it were, it would not be possible for the DOM to contain nodes that represent markup around the root element, such as a preceding comment or following processing instruction. The Document interface extends the Node interface, adding a number of methods. The first four of these methods obtain information about the document. The remainder are 'factory' methods, used to create new objects to put in the document:

DocumentType      getDoctype();
DOMImplementation getImplementation();
Element           getDocumentElement();
NodeList          getElementsByTagName(String tagName);

Element           createElement(String tagName)
                                  throws DOMException;
DocumentFragment  createDocumentFragment();
Text              createTextNode(String data);
Comment           createComment(String data);
CDATASection      createCDATASection(String data)
                                  throws DOMException;
ProcessingInstruction
        createProcessingInstruction(String target,
                                    String data)
                                  throws DOMException;
Attr              createAttribute(String name)
                                  throws DOMException;
EntityReference   createEntityReference(String name)
                                  throws DOMException;

Note that DOM Level 2 adds seven more methods to this interface, mostly for handling elements and attributes that use namespaces.

Get document type

The getDoctype method provides access to information about the document, such as the DOCTYPE name (the name of the root element), and lists of entity declarations and notation declarations, through a DocumentType interface object (explained later):

DocumentType myDocType = myDoc.getDoctype();

Get implementation

The getImplementation method provides access to information concerning the capabilities of the DOM-compliant package. It returns a reference to an object that can be queried for information on whether or not a specific feature is supported.

For example, it can be asked whether or not HTML extensions are available. The DOMImplementation interface is discussed in detail later:

DOMImplementation myDOMImpl =
                       myDoc.getImplementation();

Get document element

The getDocumentElement method returns a reference to the node that represents the root element:

Element myRootElem = myDoc.getDocumentElement();

This method returns an object of type Element (described later).

It should be noted at this point that the node representing the entire document has child nodes, including one that represents the root element. Other nodes are present if the root element is surrounded by markup, such as comments and processing instructions. It is therefore possible to gain a reference to the root element by searching through the document's children for the first (and only) node that represents an element, although this method is not as efficient as simply asking for the root element directly, as shown above.

Get descendant elements

A document may need to be searched for all occurrences of a specific element. For example, an application could extract the content of all title elements in order to construct a contents list for the document. The getElementsByTagName method returns a reference to an object that holds a list of matching element nodes:

NodeList myList = myDoc.getElementsByTagName("title");

The NodeList interface is discussed later.

Factory methods

When reading an XML document into a DOM structure, all the nodes are created by the parser. However, the DOM can be used to create new documents, or to add new structures to an existing document. It must therefore be possible for the application to create new nodes as they are needed, before attaching them to the tree (using the append or insert methods described previously).

The Document interface contains a number of so-called 'factory' methods for this purpose, including createElement, createDocumentFragment, createTextNode, createComment, createCDATASection, createProcessingInstruction, createAttribute and createEntityReference. Most of these methods take a single string parameter, giving the name to assign to the new object of the given type. The createProcessingInstruction method is one exception, as it requires two parameters (to set the target name and the instruction text). The other exception is the createDocumentFragment method, which takes no parameters. Some of the methods also throw an exception if the parameters are incorrect in any way:

try
{
  Element myElem = myDoc.createElement("para");
}
catch (DOMException err) { ... }

DocumentFragment myFragment =
      myDoc.createDocumentFragment();

TextNode myText = myDoc.createTextNode("a paragraph.");

Comment myComment =
      myDoc.createComment("edit this document");

try
{
  CDATASection myCDATASect =
      myDoc.createCDATASection("Press <ENTER>");
}
catch (DOMException err) { ... }

try
{
  ProcessingInstruction myPI =
      myDoc.createProcessingInstruction("ACME",
                                       "page-break");
}
catch (DOMException err) { ... }

try
{
  Attr myAttribute = myDoc.createAttribute("Author");
}
catch (DOMException err) { ... }

try
{
  EntityReference myEntityRef =
      myDoc.createEntityReference("company");
}
catch (DOMException err) { ... }

These methods return references to nodes of various types. These node types are discussed in detail later.