2. Document Object Model (Core) Level 1
2.8 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:
- A brief overview of the semantics of the object and
how it relates to other objects in the DOM.
- A sequence of <method signature, description>
pairs for each method that is defined for the object.
Interface DOM
The "DOM" interface provides a number of methods
for performing operations that are independent of any particular
instance of the document object model.
Although
IDL does not provide a mechanism for expressing the concept, the
methods supplied by the DOM interface will be implemented as
"static", or instance independent, methods. This means
that a client application using the DOM does not have to locate
a specific instance of the DOM object; rather, the methods are
will be available directly on the DOM class itself and so are
directly accessible from any execution context.
IDL Definition
interface DOM {
Document createDocument(in wstring type);
boolean hasFeature(in wstring feature);
};
|
Method createDocument()
Creates a document of the specified type
| type | The type of document to create, i.e.,
"HTML" or "XML". |
| Document |
An instance of an HTML or XML document is created. Documents
are a special type of DOM object because other objects (such as
Elements, DocumentFragments, etc.) can only exist within the context
of a Document. |
|
This method throws no exceptions.
|
Method hasFeature()
Returns TRUE if the current DOM implements a given
feature, FALSE otherwise.
| feature | The package name of the feature to test. |
|
This method throws no exceptions.
|
Interface 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.
IDL Definition
interface DocumentContext {
attribute Document document;
};
|
Attribute 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.
Interface DocumentFragment
DocumentFragment is the "lightweight" or "minimal" document object,
or the handle for a "fragment" as returned by the Range operations,
and it (as the superclass of Document) anchors the XML/HTML tree in a
full-fledged document.
The children of a DocumentFragment node are zero or more nodes
representing the tops of any sub-trees defining the structure of the
document, including the actual root element of the XML or HTML document,
as well as the XML prolog, comments, PIs, etc.
For a document fragment, there could be a number of
subtrees, since fragments do not need to be well-formed XML documents
(although they do need to be well-formed XML parsed entities, which
can have multiple top nodes). Criteria for "well-formedness" are
much looser in the HTML world, and the DOM will not attempt to impose
any constraints here.
For a complete HTML document, this will contain an Element instance whose
tagName is "HTML"; for a complete XML document
this will contain the
outermost element, i.e. the element non-terminal
in production [41] in Section 3
of the XML-lang specification.
IDL Definition
interface DocumentFragment : Node {
attribute Document masterDoc;
};
|
Attribute masterDoc
This provides access to the Document
object asssociated with this DocumentFragment.
Interface Document
The Document object represents the entire HTML or XML
document. Conceptually, it is the root of the document tree, and
provides the primary access to the document's data.
Since Document inherits
from DocumentFragment, its children are contents of the Document,
e.g., the root Element, the XML prolog, any processing instructions
and or comments, etc.
Since Elements, Text nodes, Comments, PIs, etc. cannot exist outside
a Document, the Document interface also anchors the "factory" methods
that create these objects.
IDL Definition
interface Document : DocumentFragment {
attribute Node documentType;
attribute Element documentElement;
attribute DocumentContextcontextInfo;
DocumentContext createDocumentContext();
Element createElement(in wstring tagName,
in AttributeList attributes);
Text createTextNode(in wstring data);
Comment createComment(in wstring data);
PI createPI(in wstring name,
in wstring data);
Attribute createAttribute(in wstring name,
in Node value);
AttributeList createAttributeList();
NodeIterator getElementsByTagName();
};
|
Attribute 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.
Attribute documentElement
This is a "convenience" attribute to jump directly to
the child node that is the root element of
the document.
Attribute contextInfo
Detailed information on where this document came from and any
additional information we need to define.
Method createDocumentContext()
Create and return a new DocumentContext.
|
This method has no parameters.
|
| DocumentContext |
A new DocumentContext
object. |
|
This method throws no exceptions.
|
Method createElement()
Create an element based on the tagName. Note that the
instance returned may implement an interface derived from
Element. The attributes parameter can be null if
no attributes are specified for the new
Element.
| tagName | The name of the element type to
instantiate. |
| attributes | The set of attributes for the element. |
| Element |
A new Element object with a set of
attributes identical to those spoecified in the parametert
list. |
|
This method throws no exceptions.
|
Method createTextNode()
Create a Text node given the specified
string.
| data | The data for the node. |
| Text |
The new Text object. |
|
This method throws no exceptions.
|
Method createComment()
Create a Comment node given the specified
string.
| data | The data for the node. |
| Comment |
The new Comment object. |
|
This method throws no exceptions.
|
Method createPI()
Create a PI node given the specified name
and data strings.
| name | The name part of the PI. |
| data | The data for the node. |
|
This method throws no exceptions.
|
Method createAttribute()
Create an Attribute of the given name and specified
value. Note that the Attribute instance can then be set on an
Element using the setAttribute method.
| name | The name of the attribute. |
| value | The value of the attribute. |
| Attribute |
A new Attribute object. |
|
This method throws no exceptions.
|
Method createAttributeList()
Create an empty AttributeList.
|
This method has no parameters.
|
| AttributeList |
A new AttributeList object. |
|
This method throws no exceptions.
|
Method getElementsByTagName()
Returns an iterator through all subordinate Elements with
a given tag name.
|
This method has no parameters.
|
| NodeIterator |
A new NodeIterator object. |
|
This method throws no exceptions.
|
Interface 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.
IDL Definition
interface Node {
// NodeType
const int DOCUMENT = 1;
const int ELEMENT = 2;
const int ATTRIBUTE = 3;
const int PI = 4;
const int COMMENT = 5;
const int TEXT = 6;
int getNodeType();
Node getParentNode();
NodeIterator getChildNodes();
boolean hasChildNodes();
Node getFirstChild();
Node getPreviousSibling();
Node getNextSibling();
Node insertBefore(in Node newChild,
in Node refChild);
Node replaceChild(in Node newChild,
in Node oldChild);
Node removeChild(in Node oldChild);
};
|
Definition group NodeType
(ED: TBD)
| DOCUMENT |
(ED: TBD)
|
| ELEMENT |
(ED: TBD)
|
| ATTRIBUTE |
(ED: TBD)
|
| PI |
(ED: TBD)
|
| COMMENT |
(ED: TBD)
|
| TEXT |
(ED: TBD)
|
Method 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 Node 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.
|
This method has no parameters.
|
| int |
The type of the node. |
|
This method throws no exceptions.
|
Method getParentNode()
Returns the parent of the given Node instance. If this
node is the root of the document object tree, or if the node has
not been added to a document tree,
null is returned.
|
This method has no parameters.
|
| Node |
The parent of the node. |
|
This method throws no exceptions.
|
Method getChildNodes()
Returns a NodeIterator object that will enumerate all children of
this node. If there are no children, an iterator that will return
no nodes is
returned. The content of the returned NodeIterator 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 nodes returned by the iterator; it is not
a static snapshot of the content of the Node. Similarly,
changes made to the nodes returned by the iterator will be
immediately reflected in the tree, including
the set of children of the Node that the NodeIterator was created
from.
|
This method has no parameters.
|
| NodeIterator |
An iterator through the children of the node. |
|
This method throws no exceptions.
|
Method hasChildNodes()
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 getChildNodes().
|
This method has no parameters.
|
| boolean |
True if the node has children. |
|
This method throws no exceptions.
|
Method getFirstChild()
Returns the first child of a node. If there is no such
node, null is returned.
|
This method has no parameters.
|
| Node |
The first child of the node, or null. |
|
This method throws no exceptions.
|
Method 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.
|
This method has no parameters.
|
| Node |
The the node immediately preceeding, or
null. |
|
This method throws no exceptions.
|
Method 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.
|
This method has no parameters.
|
| Node |
The node immediately following, or null. |
|
This method throws no exceptions.
|
Method insertBefore()
Inserts a child node (newChildbefore the
existing child node refChild. If
refChild is null, insert
newChild at the end of the list of children. If
refChild is not a child of the Node that
insertBefore is being invoked on, a
NotMyChildException is thrown.
| newChild | (ED: TBD.)
|
| refChild | (ED: TBD.)
|
| Node |
The node being inserted. |
| NotMyChildException | Thrown if refChild is not a child
of the node. |
Method replaceChild()
Replaces the child node oldChild with
newChild in the set of children of the given
node, and return the oldChild node. If
oldChild was not already a child of the node that
the replaceChild method is being invoked on, a
NotMyChildException is thrown.
| newChild | (ED: TBD.)
|
| oldChild | (ED: TBD.)
|
| Node |
The node being replaced. |
| NotMyChildException | Thrown if oldChild is not a child
of the node. |
Method removeChild()
Removes the child node indicated by
oldChild from the list of children and returns
it. If oldChild was not a child of the given
node, a NotMyChildException is thrown.
| Node |
The node being removed. |
| NotMyChildException | Thrown if oldChild is not a child of
the node. |
Interface NodeIterator
A NodeIterator is a very simple
iterator class that can be used to provide a simple
linear view of the document hierarchy. The
NodeIterator is very similar to the
NodeEnumerator interface in previous
drafts (Sun is deprecating the term
enumerator).
"Smart Iterator" is an interface being considered
by the WG that would build on top of the core Iterator
interface and allow iterators to be built via more
general filtering and querying objects
IDL Definition
interface NodeIterator {
unsigned long getLength();
Node getCurrent();
Node toNext();
Node toPrevious();
Node toFirst();
Node toLast();
Node toNth(in int Nth);
Node toNode(in Node destNode);
};
|
Method getLength()
This method returns the number of items that
will be iterated over if the iterator is started at
the beginning, and toNext() is called
repeatedly until the end of the sequence is
encountered. Note: This may be an expensive
operation.
|
This method has no parameters.
|
| unsigned long |
This method will always return the correct
number of items in a single threaded environment,
but may return misleading results in
multithreaded, multiuser situations.. |
|
This method throws no exceptions.
|
Method getCurrent()
This method returns the Node over
which the iterator currentl rests.Note: This must be presented as getCurrent in the ECMAScript
binding, not as an attribute named Current.
|
This method has no parameters.
|
| Node |
This method will return the
Node at the current position in the
interation. Note: This may be unsafe in
uncontrolled mutliuser, or multithreaded
applications.
|
|
This method throws no exceptions.
|
Method toNext()
This method alters the internal state of
the iterator such that the node it references is the
next in the sequence the iterator is presenting
relative to the current position.
|
This method has no parameters.
|
| Node |
This method returns the node that has been
traversed to, or null when it is not
possible to iterate any further. |
|
This method throws no exceptions.
|
Method toPrevious()
This method alters the internal state of
the iterator such that the node it references is the
previous node in the sequence the iterator is presenting
relative to the current position.
|
This method has no parameters.
|
| Node |
This method returns the node that has been
traversed to, or null when it is not
possible to iterate any further. |
|
This method throws no exceptions.
|
Method toFirst()
This method alters the internal state of
the iterator such that the node it references is the
first node in the sequence the iterator is presenting
relative to the current position.
|
This method has no parameters.
|
| Node |
This method will only return
null when there are no items to
iterate over. |
|
This method throws no exceptions.
|
Method toLast()
This method alters the internal state of
the iterator such that the node it references is the
last node in the sequence the iterator is presenting
relative to the current position.
|
This method has no parameters.
|
| Node |
This method will only return
null when there are no items to
iterate over. |
|
This method throws no exceptions.
|
Method toNth()
This method alters the internal state of
the iterator such that the node it references is the
Nth node in the sequence the iterator
is presenting relative to the current position.
Note: This may be a slow
operation.
| Nth | The offset relative to the current position
at which to position the iterator. |
| Node |
This method will return
null when position specified is out
of the range of legal values. |
| NoSuchNodeException | Thrown if the value specified is greater
than the number that would be returned from
getLength(). |
Method toNode()
This method alters the internal state of
the iterator such that it references the
destNode node as the current position.
Note: This may be a slow
operation.
| destNode | Destination node to make the current one. |
| Node |
This method will return
null when position specified is out
of the range of legal values. |
| NoSuchNodeException | Thrown if the value specified is greater
than the number that would be returned from
getLength(). |
Interface TreeIterator
A TreeIterator is a
NodeIterator that has additional methods that
are specific to tree navigation.
IDL Definition
interface TreeIterator : NodeIterator {
unsigned long numChildren();
unsigned long numPreviousSiblings();
unsigned long numNextSiblings();
Node toParent();
Node toPreviousSibling();
Node toNextSibling();
Node toFirstChild();
Node toLastChild();
Node toNthChild();
};
|
Method numChildren()
This method returns the number of children
that lie below the current node.
|
This method has no parameters.
|
| unsigned long |
This method will always return the correct
number of items in a single threaded environment,
but may return misleading results in
multithreaded, multiuser situations.. |
|
This method throws no exceptions.
|
Method numPreviousSiblings()
This method returns the number of siblings
that lie previous to the current node.
|
This method has no parameters.
|
| unsigned long |
This method will always return the correct
number of items in a single threaded environment,
but may return misleading results in
multithreaded, multiuser situations.. |
|
This method throws no exceptions.
|
Method numNextSiblings()
This method returns the number of siblings
that lie after to the current node.
|
This method has no parameters.
|
| unsigned long |
This method will always return the correct
number of items in a single threaded environment,
but may return misleading results in
multithreaded, multiuser situations.. |
|
This method throws no exceptions.
|
Method toParent()
Move the iterator to the parent of the current
node, if there is a parent.
|
This method has no parameters.
|
| Node |
This method will return
null when there is no parent for the
current node. |
|
This method throws no exceptions.
|
Method toPreviousSibling()
Move the iterator to the previous sibling of
the current node, if there is one.
|
This method has no parameters.
|
| Node |
This method will return
null when there is no previous
sibling for the current node. |
|
This method throws no exceptions.
|
Method toNextSibling()
Move the iterator to the next sibling of
the current node, if there is one.
|
This method has no parameters.
|
| Node |
This method will return
null when there is no next
sibling for the current node. |
|
This method throws no exceptions.
|
Method toFirstChild()
Move the iterator to the first child of
the current node, if there is one.
|
This method has no parameters.
|
| Node |
This method will return
null when there is no children
for the current node. |
|
This method throws no exceptions.
|
Method toLastChild()
Move the iterator to the last child of
the current node, if there is one.
|
This method has no parameters.
|
| Node |
This method will return
null when there is no children
for the current node. |
|
This method throws no exceptions.
|
Method toNthChild()
This method alters the internal state of
the iterator such that the node it references is the
Nth child of the current node.
|
This method has no parameters.
|
| Node |
This method will return
null when position specified is out
of the range of legal values. |
| NoSuchNodeException | Thrown if the value specified is greater
than the number that would be returned from
numChildren(). |
Interface 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.
IDL Definition
interface Attribute {
wstring getName();
attribute Node value;
attribute boolean specified;
wstring toString();
};
|
Method getName()
Returns the name of this attribute.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
Attribute value
The children of this Node define 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).
There can be multiple objects defined as the value of an attribute
because the raw attribute value can contain entity references. Thus
the value of the attribute could be represented by a single Text node,
(and always will in HTML)
or a series of Text nodes interspersed with EntityReference nodes
(in XML).
Attribute specified
If this attribute was explicitly given a value in the
original document, this will be true; otherwise, it will be
false.
Method 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.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
Interface AttributeList
AttributeList objects are used to represent collections of
Attribute objects which can be accessed by name. The Attribute
objects contained in a AttributeList may also be accessed by
ordinal index. In most cases, AttributeList objects are created
from Element objects.
IDL Definition
interface AttributeList {
Attribute getAttribute(in wstring attrName);
Attribute setAttribute(in Attribute attr);
Attribute remove(in wstring attrName);
Attribute item(in unsigned long index);
unsigned long getLength();
};
|
Method getAttribute()
Retrieve an Attribute instance from the list by its
name. If it's not present, null is returned.
|
This method throws no exceptions.
|
Method setAttribute()
Add a new attribute to the end of the list and associate
it with the given name. If the name already exists, the
previous Attribute object is replaced, and returned. If no
object of the same name exists, null is returned,
and the named Attribute is added to the end of the
AttributeList object; that is, it is accessible via the
item method using the index one less than the
value returned by getLength.
|
This method throws no exceptions.
|
Method remove()
Removes the Attribute instance named name
from the list and returns it. If the name provided does not
exist, the NoSuchAttributeException is thrown.
| NoSuchAttributeException | (ED: TBD.)
|
Method item()
Returns the (zero-based) indexth Attribute
item in the collection. If index is greater than
or equal to the number of nodes in the list, a
NoSuchAttributeException is thrown.
| NoSuchAttributeException | (ED: TBD.)
|
Method getLength()
Returns the number of Attributes in the AttributeList
instance.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
Interface 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.
IDL Definition
interface Element : Node {
wstring getTagName();
AttributeList attributes();
void setAttribute(in Attribute newAttr);
void normalize();
NodeIterator getElementsByTagName();
};
|
Method getTagName()
This method returns 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.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
Method 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.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
Method setAttribute()
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.
|
This method throws no exceptions.
|
Method normalize()
Puts all Text nodes sub-tree underneath this element into
"DOM Normal Form", i.e., Text nodes are merged so that only markup
(e.g., tags and entity references) separates Text nodes.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
Method getElementsByTagName()
Returns an iterator through all subordinate Elements with
a given tag name.
|
This method has no parameters.
|
| NodeIterator |
A new NodeIterator object. |
|
This method throws no exceptions.
|
Interface Text
The Text object contains the non-markup content of an
Element. If there is no markup inside an Element's content, the text
will be contained in a single Text object that is the child of the
Element. Any markup will parse into child elements that are siblings
of the Text nodes on either side of it, and whose content will be
represented as Text node children of the markup element.
IDL Definition
interface Text : Node {
attribute wstring data;
void append(in wstring data);
void insert(in int offset,
in wstring data);
void delete(in int offset,
in int count);
void replace(in int offset,
in int count,
in wstring data);
void splice(in Element element,
in int offset,
in int count);
};
|
Attribute 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 represented as separate objects
in the DOM.
Method append()
Append the string to the end of the character data in this
Text node
| void |
This method returns nothing. |
|
This method throws no exceptions.
|
Method insert()
Insert the string at the specified character offset.
| offset | Offset at which to insert |
| data | String to insert |
| void |
This method returns nothing. |
|
This method throws no exceptions.
|
Method delete()
Insert characters starting at the specified character offset.
| offset | Offset at which to delete |
| count | Number of characters to delete |
| void |
This method returns nothing. |
|
This method throws no exceptions.
|
Method replace()
Replace the characters starting at the specified character
offset with the specified string.
| offset | Offset at which to start replacing |
| count | Number of characters to replace |
| data | String to replace previous content with. |
| void |
This method returns nothing. |
|
This method throws no exceptions.
|
Method splice()
Insert the specified element in the tree as a sibling of the
Text node. The result of this operation may be the creation of up to
2 new Text nodes: the character data specified by the offset and count will form one Text node that
will become the child of the inserted element and the remainder of the character
data (after the offset and count) will form another Text node become a sibling
of the original Text node.
| element | Element to insert into the tree. |
| offset | Offset at which to insert. |
| count | Number of characters to copy to child Text node of element. |
| void |
This method returns nothing. |
|
This method throws no exceptions.
|
Interface 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.
IDL Definition
interface Comment : Node {
attribute wstring data;
};
|
Attribute data
The content of the comment, exclusive of the comment
begin and end sequence.
Interface 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.
IDL Definition
interface PI : Node {
attribute wstring name;
attribute wstring data;
};
|
Attribute 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.
Attribute data
The content of the processing instruction, from the
character immediately after the <? (after
the name in XML) to the character immediately preceding
the ?>.