W3CWD-DOM/level-one-core-971009


Document Object Model (Core)
Level 1

W3C Working Draft 9-October-1997

This version:
http://www.w3.org/WD-DOM/level-one-core-971009
Latest version:
http://www.w3.org/WD-DOM/level-one-core

WG Chair:
Lauren Wood, SoftQuad, Inc.

Editor:
Steve Byrne, JavaSoft (Sun Microsystems, Inc.)

Principal contributors:
Vidur Apparao, Netscape; Steve Byrne, JavaSoft (Sun Microsystems, Inc.); Mike Champion, ArborText, Inc.; Scott Isaacs, MicroSoft; Arnaud Le Hors, W3C; Gavin Nicol, INSO; Peter Sharpe, SoftQuad, Inc.; Jared Sorensen, Novell; Bob Sutor, IBM

Abstract

The Document Object Model (DOM) level one provides a mechanism for software developers and web script authors to access and manipulate parsed HTML and XML content. All markup as well as any document type declarations are made available. Level one also allows creation "from scratch" of entire web documents in memory; saving those documents persistently is left to the programmer. DOM Level one is intentionally limited in scope to content representation and manipulation; rendering, validation, externalization etc. are deferred to higher levels of the DOM.

Status of this document

This document is part of the Document Object Model Specification


Introduction

This specification defines a minimal set of objets and interfaces for accessing and manipulating document objects. The functionality specified in this draft (the "core" functionality) should be sufficient to implement higher level operations, such as querying, and filtering of a document; future drafts will add "utility" operations which can be implemented in terms of the core operations, but which may be implemented more efficiently using implementation-specific mechanisms that fall outside of the scope of this specification.

Intended Audience

The audience for this document is intended to be web script authors, software developers, and DOM implemention providers. This document presumes familiarity with concepts and terminology from HTML and XML, as well as object oriented programming. The actual DOM specification is provided in the Object Management Group's Interface Definition Language (IDL); experience with Java or C++ syntax should be sufficient to allow comprehension.

Design goals for the DOM Level One specification

Note: In the current specification, some operations can modify the document tree, but there is no model for handling concurrent access. The WG also recognises that in some situations, a document, or some of it's components, will not be modifiable, and a method for dealing with such situations needs to be defined.

Overall type hierarchy

The Document Object Model defines a representation of a hierarchy of objects (i.e. a tree, or "structure model"), called "nodes". The object hierarchy is typically created from a source representation such as HTML or XML via some implementation-specific mechanism that falls outside the scope of this specification.

Primary object model types

Node
  |
  +--Document
  |
  +--Element
  |
  +--Attribute
  |
  +--Text
  |
  +--Comment 
  |
  +--PI 
  |
  +--Reference
  |    |
  |    +--NamedCharacterReference
  |
  +--NumericCharacterReference

Auxiliary types

These types are "helpers" which can appear in various parts of the DOM. Some of them occur quite frequently in common usage; others are limited to the Document Type Definition section of the document, and thus may be of little interest to typical DOM users. Those types are marked accordingly.
NodeList
Represents a (possibly) lazily evaluated set of nodes.
NamedNodeList
Similar to a NodeList, but members are indexed by name.
NodeEnumerator
Used for iterating over (enumerating) a set of nodes.
DocumentContext
A repository for meta-data about a document, such as source, creation date, and other creation context information. This object will be fully specified in the level two DOM specification.
Selection
[Coming in a later draft of level one] Selections represent a range of document content, including markup, which may span partial subtrees of the document content.

IDL Issues

The primary Document Object Model type definitions are presented using the Object Management Group's Interface Definition Language (IDL, ISO standard 14750). While a complete tutorial on the IDL language is beyond the scope of this document, a few key items deserve explicit mentioning:

For more information on OMG's IDL, please visit the OMG home page, or download the CORBA 2.0 (minor version number is expected to change in the near future) specification (it's rather large) which contains the IDL language definition in chapter 3.

Note: The Object Management Group Interface Definition Language (OMG IDL) was chosen as it was designed for specifying language and implementation-neutral interfaces. Various other IDLs could be used; the use of OMG IDL does not imply a requirement to use a specific object binding runtime.


Primary API Types

The types described in this section are those that application programmers using the DOM will encounter most frequently. A good working knowledge of these types will be sufficient to accomplish most tasks.

Node

Node is the base type of most objects in the Document Object Model. It may have an arbitrary number (including zero) of sequentially ordered child nodes. It usually has a parent Node; the exception being that the root Node in a document hierarchy has no parent.

Element

Element objects represent the elements in the HTML or XML document. Elements contain, as child nodes, all the content between the start tag, and the end tag of an element. Additionally, Element objects have a list of Attribute objects which represent the combination of those attributes explicitly specified in the document, and those defined the document type definition which have default values.

Document

The Document object represents the root node of a document. It typically* has no parent; the getParentNode() method will return null.

Typical operation

Normally, a DOM-compliant implementation will make the main Document instance available to the application* through some implementation-specific mechanism. For example, a typical implementation would pass the application a reference to a DocumentContext object. From the DocumentContext, the application may retrieve the Document object, which is the root of the document object hierarchy.

Once the application has access to the root of the document object hierarchy, it can use the methods defined herein for accessing individual nodes, selection of specific node types such as all images, and so on.

Document Object Model APIs

This section defines the complete set of objects and methods which are defined by the Document Object Model. The general structure of these object definitions is:

Document

The Document object represents the entirety of an HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.
Node documentType
For XML, this provides access to the Document Type Definition (see DocumentType) associated with this XML document. For HTML documents and XML documents without a document type definition this returns the value null.
Element documentElement
The element that's the root element for the given document. For HTML, this will be an Element instance whose tagName is "HTML"; for XML this is the outermost element, i.e. the element non-terminal in production [23] in Section 2.9 of the XML-lang specification.

DocumentContext

The DocumentContext object represents information that is not strictly related to a document's content; rather, it provides the information about where the document came from, and any additional meta-data about the document. For example, the DocumentContext for a document retrieved using HTTP would provide access to the HTTP headers which were retrieved with the document, the URL that the document came from, etc.

For documents which were not retrieved via HTTP, or for those which were created directly in memory, there may be no DocumentContext.

NOTE: The DocumentContext interface described here is expected to be significantly expanded in the level two specification of the Document Object Model.

Document document
This is the root node of a Document Object Model. Any iteration, enumeration or other traversal of the entire document's content should begin with this node.

Node

The Node object is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. Nodes may have, but are not required to have, an arbitrary number of child nodes.
NodeType getNodeType()
Returns an indication of the underlying Node object's type. The actual type of the returned data is language binding dependent; the IDL specification uses an enum, and it is expected that most language bindings will represent this runtime-queryable Ndoe type using an integral data type. The names of the node type enumeration literals are straightforwardly derived from the names of the actual Node subtypes, and are fully specified in the IDL definition of Node in the IDL definition in Appendix A.
Node getParentNode()
Returns the parent of the given Node instance. If this node is the root of the document object tree, null is returned. [Note: because in ECMAScript get/set method pairs are surfaced as properties, Parent would conflict with the pre-defined Parent property, so we disambiguate this with "ParentNode" even though it is inconsistent with the naming convention of the other methods that do not include "Node"].
Node getFirstChild()
Returns the first child of a node. If there is no such node, null is returned.
NodeList getChildren()
Returns a NodeList object containing the children of this node. If there are no children, null is returned. The content of the returned NodeList is "live" in the sense that changes to the children of the Node object that it was created from will be immediately reflected in the set of Nodes the NodeList contains; it is not a static snapshot of the content of the Node. Similarly, changes made to the NodeList will be immediately reflected in the set of children of the Node that the NodeList was created from.
boolean hasChildren()
Returns true if the node has any children, false if the node has no children at all. This method exists both for convenience as well as to allow implementations to be able to bypass object allocation, which may be required for implementing getChildren().
Node getPreviousSibling()
Returns the node immediately preceding the current node in a breadth-first traversal of the tree. If there is no such node, null is returned.
Node getNextSibling()
Returns the node immediately following the current node in a breadth-first traversal of the tree. If there is no such node, null is returned.
Node insertChild(in unsigned long index, in Node newChild)
Inserts a child node into the list of children before zero-based location index. Nodes from index to the end of list are moved up by one. If index is 0, the node is added as the first child; if index is greater than or equal to the number of children, the node is added as the last child.
Node replaceChild(in unsigned long index, in Node newChild)
Replaces the child node at location index and returns the old Node that occupied that position. If the index is provided is larger than the number of nodes in the list, a NoSuchNodeException is thrown.
Node removeChild(in unsigned long index)
Removes the child node at location index and returns the old Node that occupied that position. If the index is provided is larger than the number of nodes in the list, a NoSuchNodeException is thrown.
NodeEnumerator getElementsByTagName(wstring name)
Produces an enumerator which iterates over all of the Element nodes that are descendants of the current node whose tagName matches the given name. The iteration order is a depth first enumeration of the elements as they occurred in the original document.

Note: a later level of the DOM will provide a more generalized querying mechanism for Nodes. One such query involves obtaining all the Elements in a subtree with a given tagName. A convenience method for this query has been included in the core document. This method might be removed at a later date in favor of a more comprehensive querying mechanism.

NodeList

The NodeList object provides the abstraction of an ordered collection of Nodes, without defining or constraining how this collection is implemented, allowing different DOM implementations to be tuned for their specific environments.

The items in the NodeList are accessible via an integral index, starting from 0. A NodeEnumerator object may be created to allow simple sequential traversal over the members of the list.

NodeEnumerator getEnumerator()
Creates and returns an object which allows traversal of the nodes in the list in an iterative fashion. Note this method may be very efficient in some implementations; that is, they can return the enumerator instance even before the first node in the set has been located.
Node item(in unsigned long index) raises(NoSuchNodeException)
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, a NoSuchNodeException is thrown.
Node replace(in unsigned long index, in Node replacedNode) raises (NoSuchNodeException)
Replace the indexth item the list with replacedNode, and return the old node object at that index (null is returned if the index is equal to the previous number of nodes in the list). If index is greater than the number of nodes in the list, a NoSuchNodeException is thrown.
void append(in Node newNode)
A convenience function to add a new item at the end of the NodeList instance. Equivalent to insert(self.getLength(), newNode).
void prepend(in Node newNode)
A convenience function to add a new item at the beginning of the NodeList instance. Equivalent to insertChild(0, newNode).
void insert(in unsigned long index, in Node newNode) raises (NoSuchNodeException)
Inserts a child node into the list BEFORE zero-based location index. Nodes from index to the end of list are moved up by one. If index is 0, the node is added at the beginning of the list; if index is self.getLength(), the node is added at the end of the list.
Node remove(in unsigned long index) raises (NoSuchNodeException)
Removes the node at index from the list and returns it. The indices of the members of the list which followed this node are decremented by one following the removal. If the index is provided is larger than the number of nodes in the list, the NoSuchNodeException is thrown.
unsigned long getLength()
Returns the number of nodes in the NodeList instance. The range of valid child node indices is 0 to getLength()-1 inclusive.

NodeEnumerator

This class provides a generic iteration mechanism over an arbitrary collection of nodes. The nodes may be enumerated in either forward or reverse order, and the direction of enumeration may be changed at any time. The enumerator behaves as though it had an internal "pointer" to the current node, and provides methods for abstractly changing the notion of what the current node is.

Typical usage (in some C++ like language) might look like:

    NodeEnumerator nodeEnum = document.getChildren().getEnumerator();

    for (Node node = nodeEnum.first(); node != null; node = nodeEnum.next()) {

	// ... do some computation on that node
    }

Node getFirst()
Returns the first node that the enumeration refers to, and resets the enumerator to reference the first node. If there are no nodes in the enumeration, null is returned.

NOTE: in some implementations this may or may not be a fast operation; it may be the case that the enumeration finds the requested node on demand, and for very large document object, this may take some time.

Node getNext()
Return the next node in the enumeration, and advances the enumeration. Returns null after the last node in the list has been passed, and leaves the current pointer at the last node.
Node getPrevious()
Return the previous node in the enumeration, and regresses the enumeration. Returns null after the first node in the enumeration has been returned, and leaves the current pointer at the first node.
Node getLast()
Retuns the last node in the enumeration, and sets the enumerator to reference the last node in the enumeration. If the enumeration is empty, this method will return null. Doing a getNext() immediately after this operation will return null.
Node getCurrent()
This returns the node that the enumeration is currently referring to, without affecting the state of the enumeration object in any way. When invoked before any of the enumeration positioning methods above, the node returned will be the first node in the enumeration, or null if the enumeration is empty.
boolean atStart()
Returns true if the enumeration's "pointer" is positioned at the start of the set of nodes, i.e. if getCurrent() will return the same node as getFirst() would return. For empty enumerations, true is always returned. Does not affect the state of the enumeration in any way.
boolean atEnd()
Returns true if the enumeration's "pointer" is positioned at the end of the set of nodes, i.e. if getCurrent() will return the same node as getLast() would return. For empty enumerations, true is always returned. Does not affect the state of the enumeration in any way.

NamedNodeList

NamedNodeList objects are used to represent collections of Node objects which can be accessed by name. The Node objects contained in a NamedNodeList may also be enumerated, and accessed by ordinal index.
Node getNode(in wstring name)
Retrieve a node by its name.
Node setNode(in wstring name, in Node node)
Add a new node to the end of the collection and associate it with the given name. If the name already exists, the previous contents are replaced, and returned. If no object of the same name exists, null is returned, and the named node is added to the end of the NamedNodeList object; that is, it is accessible via the item method using the index one less than the value returned by getLength().
Node remove(in wstring name) raises (NoSuchNodeException)
Removes the named name from the list and returns it. If the name provided does not exist, the NoSuchNodeException is thrown.
Node item(in unsigned long index) raises(NoSuchNodeException)
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, a NoSuchNodeException is thrown.
unsigned long getLength()
Returns the number of nodes in the NamedNodeList instance.
NodeEnumerator getEnumerator()
Creates and returns an object which allows traversal of the nodes in the list in an iterative fashion. Note this method may be very efficient in some implementations; that is, they can return the enumerator instance even before the first node in the set has been located.

Element

By far the vast majority (apart from text) of node types that authors will generally encounter when traversing a document will be Element nodes. These objects represent both the element itself, as well as any contained nodes.

For example (in XML):

<elementExample id="demo">
    <subelement1/>
    <subelement2>
	<subsubelement/>
    </subelement2>
</elementExample>
When represented using DOM, the top node would be "elementExample", which contains two child Element nodes (and some space), one for "subelement1" and one for "subelement2". "subelement1" contains no child nodes of its own.
wstring tagName
This is the string that is the element's name. For example, in:
<elementExample id="demo">
    ...
</elementExample>
This would have the value "elementExample". Note that this is case-preserving, as are all of the operations of the DOM. See Name case in the DOM for a description of why the DOM preserves case.

Note:This attribute's name may change in the near future to "elementType", which is a more technically correct term.

NamedNodeList attributes
The attributes for this element. In the elementExample example above, the attributes list would consist of the id attribute, as well as any attributes which were defined by the document type definition for this element which have default values.
void setAttribute(in Attribute newAttr)
Adds a new attribute/value pair to an Element node object. If an attribute by that name is already present in the element, it's value is changed to be that of the Attribute instance.

Attribute

The Attribute object represents an attribute in an Element object. Typically the allowable values for the attribute are defined in a document type definition.
wstring name
The name of this attribute. Note that this name is case-sensitive, and is not changed or canonicalized by the DOM. See casing for further details.
NodeList value
The effective value of this attribute. (The attribute's effective value is determined as follows: if this attribute has been explicitly assigned any value, that value is the attribute's effective value; otherwise, if there is a declaration for this attribute, and that declaration includes a default value, then that default value is the attribute's effective value; otherwise, the attribute has no effective value.) Note, in particular, that an effective value of the null string would be returned as a Text node instance whose toString() method will return a zero length string (as will toString() invoked directly on this Attribute instance). If the attribute has no effective value, then this method will return null. Note the toString() method on the Attribute instance can also be used to retrieve the string version of the attribute's value(s).

Even seemingly simple string-valued attributes will be represented as a set of more than one Node if the value of the attribute includes things like entity references. For example:

    <p class="foo&amp;bar">
The nodes would be a Text containing "foo", then a NamedCharacterReference, and finally a Text instance containing "bar".
boolean specified
If this attribute was explicitly given a value in the original document, this will be true; otherwise, it will be false.
wstring toString()
Returns the value of the attribute as a string. Character and general entity references will have been replaced with their values in the returned string.

Comment

Represents the content of a comment, i.e. all the characters between the starting '<!--' and ending '-->'. Note that this is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.
wstring data
The content of the comment, exclusive of the comment begin and end sequence.

PI

A PI node is a "processing instruction". The content of the PI node is the entire content between the delimiters of the processing instruction.
wstring name
XML defines a name as the first token following the markup that begins the processing instruction, and this attribute returns that name. For HTML, the returned value is null.
wstring data
The content of the processing instruction, from the character immediately after the <? (after the name in XML) to the character immediately preceding the ?>.

Reference

This is the base type for named entities, including parameter entities, but not numeric character entities. It specifies the name of the reference, and contains a pointer to the object that defines the value of the entity.
wstring name
The name of the entity being referred to.

NamedCharacterReference

A subtype of Reference, used for representing named references to characters, such as &lt; or &amp;.
wstring getReplacementText()
Returns the string that consists of the actual character that the NamedCharacterReference refers to. For example, for &lt;, the returned string would be "<".

NumericCharacterReference

NumericCharacterReference objects are used to represent explicit references to characters via numeric literals, such as &#60; or &#x48;. Applications may retrieve both the actual Character object corresponding to this numeric value, and they can also retrieve actual digits (and any associated radix-indicating prefix) of the original reference.
wchar character
The Character instance that this character reference indicated.
wstring original
This is the original string representing the numeric character reference, without the introducing markup. For example, given &#60; this attribute would be "60" (sans the '&#' and ';'), and for &#x48;, this attribute would have "x48" for its value.

Text

The Text object contains the non-markup portion of a document. For XML documents, all whitespace between markup results in Text nodes being created.
wstring data
This holds the actual content of the text node. Text nodes contain just plain text, without markup and without entities, both of which are manifest as separate objects in the DOM.
boolean isIgnorableWhitespace
This is true if the Text node contains only whitespace, and if the whitespace is ignorable by the application. Only XML processors will make use of this, as HTML abides by SGML's rules for whitespace handling.

Footnotes

The term "Application"

This document uses the the term "application" to mean the set of code that is using the DOM to inspect and manipulate the document object; i.e. scripts and/or full-scale applications.

Nested Documents

Sometimes it may make sense to have a document node be stored as child of another node. For example, at some point during the creation of a document that's representing XML links, it may be valuable to be able to have the target document(s) directly accessible in the node hierarchy.

Whitespace in XML

Parsed XML includes text nodes for white space between elements, even if there is nothing but whitespace present. The text node contains an indication of whether or not the author of the document intended for the whitespace to be ignored, but, according to the XML specification, white space must be passed to the DOM verbatim.

Name case in the DOM

The Document Object Model does not change the case of any identifiers present in a parsed document. XML preserves the case of identifiers (and indeed recognizes upper and lower case versions of the same identifier as distinct), and the HTML specification says that markup is handled case-insensitively, and many implementations of HTML tools interpret this to mean lowercase. So, in order to not lose case information, the methods in the Document Object Model do not alter the case of returned identifiers.

Application developers using the DOM for HTML would be wise to use case-insensitive comparisons when testing for equality.

Appendix A: IDL Interface definitions

Shown below are the core IDL definitions for the objects in the Document Object Model. The HTML IDL definition is here, and the XML IDL definition, including the types to represent the document type definition is here.

// $Date: 1997/10/07 19:37:20 $
module DOM {

  // Basic grove object types
  interface Node;
  interface Document;

  // Objects related to the instance
  interface Element;

  typedef sequence StringList;


  exception NoSuchNodeException {};


  //////////////////////////////////////////////////////////////////////////
  //                                                                      //
  // OBJECTS USED TO DEFINE A GROVE                                       //
  //                                                                      //
  //////////////////////////////////////////////////////////////////////////

  // Enumerator class for a node list
  interface NodeEnumerator {
    Node getFirst();
    Node getNext();
    Node getPrevious();
    Node getLast();

    Node getCurrent();

    // not sure about these...
    // the rationale for their existence is that the enumerator may be used
    // internally to a method, which may return some interesting value, and
    // therefore cannot also indicate whether the start or end of enumeration
    // was reached.  Any of the traversal methods affects the state, and
    // so are not suitable for usage as predicates (unless possible state
    // manipulation is acceptable).
    boolean atStart();
    boolean atEnd();
  };

  // Define the type for a sequence of nodes
  interface NodeList {
    NodeEnumerator getEnumerator();

    Node item(in unsigned long index)
        raises(NoSuchNodeException);

    void replace(in unsigned long index, in Node replacedNode) 
	raises (NoSuchNodeException);

    void append(in Node newNode);

    void prepend(in Node newNode);

    void insert(in unsigned long index, in Node newNode) 
        raises (NoSuchNodeException);

    Node remove(in unsigned long index)
        raises (NoSuchNodeException);

    // This may be expensive to compute
    unsigned long     getLength();
  };

  // Interface to a node in a grove
  interface Node {
    
    enum NodeType {
         NODE,
 	 DOCUMENT,
         ELEMENT,
         ATTRIBUTE,
         PI,
         COMMENT,
         REFERENCE,
         NAMED_CHARACTER_REFERENCE,
         NUMERIC_CHARACTER_REFERENCE,
	 TEXT
    };
    
    NodeType getNodeType();

    // Simple traversal interface
    Node     getParentNode();
    NodeList getChildren();
    boolean  hasChildren();
    Node     getPreviousSibling();
    Node     getNextSibling();

    void insertChild(in unsigned long index, in Node newChild);

    Node replaceChild(in unsigned long index, in Node newChild)
        raises (NoSuchNodeException);

    Node removeChild(in unsigned long index)
        raises (NoSuchNodeException);

    NodeEnumerator getElementsByTagName(in wstring name);
  };

  // Named node list
  interface NamedNodeList {
    // Core get and set interface. Note that implementations may
    // build the list lazily
    Node getNode(in wstring name);
    Node setNode(in wstring name, in Node node);

    Node remove(in wstring name) raises (NoSuchNodeException);

    Node item(in unsigned long index)
        raises(NoSuchNodeException);

    unsigned long getLength();

    NodeEnumerator getEnumerator();
  };

  
  // Placeholders
  typedef wstring Date;
  typedef wstring Location;

  //////////////////////////////////////////////////////////////////////////
  //                                                                      //
  // OBJECTS RELATED TO THE INSTANCE                                      //
  //                                                                      //
  //////////////////////////////////////////////////////////////////////////

  interface DocumentContext {
    attribute Document	document;
  };

  interface Document : Node {
    attribute Node      documentType;

    attribute Element 	documentElement;
  };

  interface Attribute : Node {
    attribute wstring	name;

    attribute NodeList  value;

    attribute boolean	specified;

    // provides a connection to the DTD 
    // attribute Node  	definition;

    wstring toString();
  };

  interface PI : Node {
    attribute wstring 	name;
    attribute wstring 	data;
  };

  interface Element : Node {
    attribute wstring	tagName;

    attribute NamedNodeList  attributes;

    void setAttribute(in Attribute newAttr);
  };

  // Represents the content of 
  interface Comment : Node {
    attribute wstring	data;
  };

  // base type for named entities, including parameter entities, but not
  // numeric entites
  interface Reference : Node {
    attribute wstring	name;

    // Entity will be defined in a later draft of the level one specification
    //attribute Entity	definition;
  };

  interface NamedCharacterReference : Reference {
    wstring getReplacementText();
  };

  interface NumericCharacterReference : Node {
    attribute wchar character;

    // The "60" part of < or "x48" for H
    attribute wstring original;
  };


  interface Text : Node {
     attribute wstring    data;

     attribute boolean isIgnorableWhitespace;
  };

};



Appendix B: Java Core API definitions

Note:All of the classes have zero argument constructors implicitly. To build a new Document Object Model tree, it is sufficient to just create the objects that are needed, populate their attributes, etc, and connect them together to form the parent-child and other relationships as needed.

Node.java

// $Id: Node.java,v 1.13 1997/10/07 19:37:55 sbb Exp $

package w3c.dom;

public interface Node {
    // Node type enumeration; these represent the set of
    //  values returned by the getNodeType() method.
    static final int NODE      = 1;
    static final int DOCUMENT  = 2;
    static final int ELEMENT   = 3;
    static final int ATTRIBUTE = 4;
    static final int PI        = 5;
    static final int COMMENT   = 6;
    static final int REFERENCE = 7;
    static final int NAMED_CHARACTER_REFERENCE = 8;
    static final int NUMERIC_CHARACTER_REFERENCE = 9;
    static final int TEXT      = 10;

    int getNodeType();

    // can return null
    Node getParentNode();

    NodeList getChildren();
    boolean  hasChildren();
    Node     getPreviousSibling();
    Node     getNextSibling();

    void insertChild(int index, Node newChild);


    Node replaceChild(int index, Node newChild)
	 	 throws NoSuchNodeException;

    Node removeChild(int index)
	 	 throws NoSuchNodeException;

    NodeEnumerator getElementsByTagName(String name);
}

NodeList.java

// $Id: NodeList.java,v 1.2 1997/10/07 19:37:56 sbb Exp $

package w3c.dom;

public interface NodeList {
    NodeEnumerator getEnumerator();

    Node item(int index)
	 throws NoSuchNodeException;

    void replace(int index, Node replacedNode) 
	 throws NoSuchNodeException;

    void append(Node newNode);

    void prepend(Node newNode);

    void insert(int index, Node newNode) 
	 throws NoSuchNodeException;

    Node remove(int index)
	 throws NoSuchNodeException;

    // This may be expensive to compute
    int getLength();
}

NamedNodeList.java

// $Id: NamedNodeList.java,v 1.5 1997/10/07 19:37:54 sbb Exp $

package w3c.dom;

public interface NamedNodeList {
    // Core get and set interface. Note that implementations may
    // build the list lazily
    Node getNode(String name);
    Node setNode(String name, Node node);

    Node remove(String name)
	 throws NoSuchNodeException;

    Node item(int index)
	 throws NoSuchNodeException;

    int getLength();

    NodeEnumerator getEnumerator();
}

NodeEnumerator.java

// $Id: NodeEnumerator.java,v 1.5 1997/10/07 19:37:55 sbb Exp $

package w3c.dom;

public interface NodeEnumerator {
    Node getFirst();
    Node getNext();
    Node getPrevious();
    Node getLast();

    Node getCurrent();

    // not sure about these...
    // the rationale for their existence is that the enumerator may be used
    // internally to a method, which may return some interesting value, and
    // therefore cannot also indicate whether the start or end of enumeration
    // was reached.  Any of the traversal methods affects the state, and
    // so are not suitable for usage as predicates (unless possible state
    // manipulation is acceptable).

    boolean atStart();
    boolean atEnd();
}

DocumentContext.java

// $Id: DocumentContext.java,v 1.3 1997/10/07 19:37:51 sbb Exp $

package w3c.dom;

public interface DocumentContext {
    Document getDocument();
    void setDocument(Document document);
}

Document.java

// $Id: Document.java,v 1.4 1997/10/07 19:37:51 sbb Exp $

package w3c.dom;

public interface Document extends Node {
    Node getDocumentType();
    void setDocumentType(Node documentType);

    Element getDocumentElement();
    void setDocumentElement(Element documentElement);
}

Attribute.java

// $Id: Attribute.java,v 1.4 1997/10/07 19:37:50 sbb Exp $

package w3c.dom;


public interface Attribute extends Node {
    String getName();
    void   setName(String name);

    NodeList getValue();
    void     setValue(NodeList value);

    boolean getSpecified();
    void    setSpecified(boolean specified);

    String toString();
}

PI.java

// $Id: PI.java,v 1.4 1997/10/07 19:37:57 sbb Exp $

package w3c.dom;

public interface PI extends Node {
    String getName();
    void   setName(String name);

    String getData();
    void   setData(String data);
}

Element.java

// $Id: Element.java,v 1.4 1997/10/07 19:37:52 sbb Exp $

package w3c.dom;

public interface Element extends Node {
    String getTagName();
    void setTagName(String tagName);

    NamedNodeList  getAttributes();
    void setAttributes(NamedNodeList attributes);

    void setAttribute(Attribute newAttr);
}

Comment.java

// $Id: Comment.java,v 1.3 1997/10/07 19:37:50 sbb Exp $

package w3c.dom;

// Represents the content of 

public interface Comment extends Node {
    String getData();
    void   setData(String data);
}

Reference.java

// $Id: Reference.java,v 1.3 1997/10/07 19:37:57 sbb Exp $

package w3c.dom;

// base type for named entities, including parameter entities, but not
// numeric entites

public interface Reference extends Node {
    String getName();
    void   setName(String name);

    // not until the DTD exists
    //attribute Entity	definition;
}

NamedCharacterReference.java

// $Id: NamedCharacterReference.java,v 1.1 1997/10/07 19:37:54 sbb Exp $

package w3c.dom;

// For Named character references

public interface NamedCharacterReference extends Reference {
    String getReplacementText();
}

NumericCharacterReference.java

// $Id: NumericCharacterReference.java,v 1.3 1997/10/07 19:37:56 sbb Exp $

package w3c.dom;

public interface NumericCharacterReference extends Node {
    char getCharacter();
    void setCharacter(char character);

    // The "60" part of < or "x48" for H
    String getOriginal();
    void   setOriginal(String original);
}

Text.java

// $Id: Text.java,v 1.3 1997/10/07 19:37:58 sbb Exp $

package w3c.dom;

public interface Text extends Node {
     String getData();
     void   setData(String data);

     boolean getIsIgnorableWhitespace();
     void    setIsIgnorableWhitespace(boolean isIgnorableWhitespace);
}

NoSuchNodeException.java

// $Id: NoSuchNodeException.java,v 1.3 1997/09/26 17:57:36 sbb Exp $

package w3c.dom;

public class NoSuchNodeException extends Exception {

    // Adds nothing over the base Exception class.

}

Appendix C: ECMAScript Core API definitions

Note: This section will contain the complete DOM core bindings for ECMAScript when they become available. We expect this to occur in the very near future as the level one core specification reaches maturity.

Appendix D: Glossary

There are a large number of terms that the DOM uses which may not be familiar to many of the readers. We suggest that you review the glossary if you encounter terms that aren't familiar.