2. Document Object Model (Core) Level 1
Editors
Mike Champion, ArborText (from November 20, 1997)
Steve Byrne, JavaSoft (until November 19, 1997)
Level One of the Document Object Model (DOM) level one
provides a common API for software developers and web script
authors to access and manipulate parsed HTML and XML content
inside conforming products. 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
methods to represent and manipulate document structure and
content; a standard API for controlling how documents are
rendered via stylesheets, validated against a DTD, accessed by
given users, etc. will be specified in a subsequent revision
level of the DOM.
2.1. Introduction
This specification defines a minimal set of objects 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
"convenience" 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.
2.2. Intended Audience
The audience for this document is intended to be web script
authors, software developers, and DOM implementation
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.
2.3. Design goals for the DOM Level One specification
It is important to note that the DOM is an
"abstraction", or an idealized model of how
documents are represented and manipulated in the products that
support the DOM interfaces. Or, even more ideally, one might
think of the DOM as the "abstract base classes" that
products supporting the DOM actually implement. Thus, in
general, HTML and XML products that support the DOM merely
"expose" the DOM as a means of accessing and
manipulating their (possibly proprietary) internal data
structures and operations; there is no assumption that they
are internally built on the DOM APIs or that they do not
expose proprietary APIs that have no relationship to the W3C
DOM.
The DOM objects and interfaces are designed to be:
- high-fidelity: sufficient for representing the
content of parsed HTML and XML documents without loss of
[significant] information. The supported HTML version is
4.0; the supported XML version is 1.0.
- isomorphic with XML: The DOM should be sufficient
to construct an entirely new document instance
programmatically that is identical to the parsed form of
a given HTML or XML document. This means that it has
sufficient constructive power to build any useful
document object hierarchy, and that an implementation
could be written such that the external document parser
merely calls the methods specified in the level one
specification to build the object hierarchy.
- extensible: The DOM core is the foundation for the
rest of the document object model levels, which means
it must be simple, flexible, and extensible.
- thread-safe: The operations supported by the DOM
will not corrupt the document object or return corrupted
state (as far as this API is concerned). Higher level
consistency support mechanisms such as explicit locks or
transactions are outside of the scope of the level one
specification. For level one of the DOM, the assumption
is that only one thread operates on the document at a
time.
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 its components, will not
be modifiable, and a method for dealing with such situations
needs to be defined in a subsequent revision level of the
DOM.
2.3.1. Entities and the DOM Core
In the DOM core, there are no objects representing
entities. Numeric character references and references to the
pre-defined entities in HTML and XML, are replaced by the
single character that makes up the entitity's replacement.
For example, in:
<p>This is a dog & a cat</p> |
the "&"
will be replaced by the character "&", and the
text in the <p> element will form a single continuous
sequence of characters. The representation of general
entities, both internal and external, are defined within the
XML-specific portion of the level one specification.Note: When a DOM representation of a document is serialized
as XML or HTML text, applications will need to check each
character in text data to see if it needs to be escaped
using a numeric or pre-defined entity. Failing to do so
could result in invalid HTML or XML.
2.4. 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:
- In the DOM's IDL definition, within each interface
there are primarily two kinds of things:
- Attribute definitions
- Method (IDL calls them "operation")
definitions
- Attribute definitions are a shorthand
notation for a pair of "get/set" or
accessor/mutator methods, and should not be
thought of, nor mapped in a particular language binding
to, data members directly.
- The "constructor" methods for the various
IDL objects are not specified explicitly. Specific
programming language implementations of the DOM will
provide suitable object creation methods; typically
these will be simple with no argument constructors,
although this is not a requirement. For the most part, DOM users will call the createXXX()
methods on the Document class to create instances of
DOM objects that are associated with a given document.
- IDL's
long datatype represents 32
signed bit integers. In other language bindings, for
example Java, this would be mapped to the Java
int datatype.
More information on IDL is available from OMG
and in chapter 3 of the CORBA 2.0
specification.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.
2.5. 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.
2.5.1. 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.
2.5.2. 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 in the document type definition
which have default values.
2.5.3. DocFragment
The DocFragment
object represents the root of a lightweight document or
document fragment.
2.5.4. Document
The Document object
extends the DocFragment interface to represent the root node
of a standalone document.
2.6. 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.
2.6.1. NodeIterator
The NodeIterator
object is used for iterating over a set of nodes specified
by a "filter". Iterators are described in detail in the book
Design Patterns, pages 257-271, from which the
following sections are quoted:
- Intent
- Provide a way to access elements of an aggregate
object sequentially without exposing it's underlying
representation.
- Applicability
- Use the Iterator pattern
- to access an aggregate object's content
without exposing it's internal
representation.
- to support multiple traversals of
aggregate objects.
- to provide a uniform interface for
traversing different aggregate structures
(that is, to support polymorphic
iteration).
2.6.2. AttributeList
The AttributeList object
represents a collection of Attribute objects, indexed by
attribute name.
2.6.3. DocumentContext
The DocumentContext object
is 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.
2.6.4. DOM
The DOM object provides
document basic operations such as creating new top-level
HTML or XML documents, or making inquiries about specific
supported versions of HTML and XML within a particular
document object model implementation.
2.6.5. Range
The Range object
[Being discussed for possible inclusion in a later
draft of level one] represents a part of the
document, potentially including markup.
2.7. 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.
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();
TreeIterator createTreeIterator(in Node node);
NodeIterator getElementsByTagName(in wstring tagname);
};
|
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 createTreeIterator()
Create a TreeIterator anchored on a given node.
| node | The "root" node of this tree iterator. |
| TreeIterator |
A new TreeIterator object. |
|
This method throws no exceptions.
|
Method getElementsByTagName()
Returns an iterator through all subordinate Elements with
a given tag name.
| tagname | The name of the tag to match on |
| 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) interface NotMyChildException {};
;
Node replaceChild(in Node newChild,
in Node oldChild) interface NotMyChildException {};
;
Node removeChild(in Node oldChild) interface NotMyChildException {};
;
};
|
Definition group NodeType
| DOCUMENT |
|
| ELEMENT |
|
| ATTRIBUTE |
|
| PI |
|
| COMMENT |
|
| TEXT |
|
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. [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"].
|
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.
| 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.
| 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 simple iterator interface
that can be used to provide a linear view of the document
hierarchy. The NodeIterator is similar in concept to a the Java
"Enumeration" interface, but has a much richer set of methods: Java
enumerators objects implementing the java.util.Enumeration interface)
iterate across a set of Objects; the first element in the set is
retrieved by the first call to a nextElement() method, and subsequent
calls to nextElement() return each dditional element in the set in
succession. A boolean hasMoreElements() method may be called to
determine whether there are more elements in the set that have not
been returned yet.
The DOM NodeIterator interface allows the same basic
operation: The first Node in a set of nodes defined by
a NodeIterator is returned by a call to the getNextNode()
method, and subsequent calls to getNextNode() will return
the rest of the set. The NodeIterator, however, lets
the caller re-position the iterator to the beginning or
the end of the set of Nodes, to determine how many
members of the set there are, position the iterator to an arbitrary
point in the set (either by position or by looking up
a particular Node), to get the current position, and
to iterate either forwards or backwards
through the set from the current position.
The "current position" and how it changes as the
iterator is used to traverse the set of defined nodes OR the set
of defined nodes changes needs to be defined more rigorously.
The "current" position is not ON a node, but at a spot in the
set just previous to the node that getNextNode() will return.
The initial position of the iterator is just before the
first node, so the first call to getNextNode() will return
the first node; if getPreviousNode() is called at the initial
position, null is returned.. If a node
is inserted before the node just after the iterator position,
it will be returned by getNextNode(); likewise if a node is
inserted after the node just previous to the iterator
position, it will be return by the next getPrevNode() call.
IDL Definition
interface NodeIterator {
unsigned long getLength();
unsigned long getCurrentPos();
boolean atFirst();
boolean atLast();
Node toNextNode();
Node toPrevNode();
Node toFirstNode();
Node toLastNode();
Node moveTo(in int n);
};
|
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 getCurrentPos()
This method returns the current position of the
iterator, where "0" is the initial position before the
first node in the set. Note: This may be an expensive
operation.
|
This method has no parameters.
|
| unsigned long |
This method will always return the correct
position in a single threaded environment,
but may return misleading results in
multithreaded, multiuser situations.. |
|
This method throws no exceptions.
|
Method atFirst()
Returns TRUE if the iterator is positioned
at the beginning of the set of nodes it will iterate over.
|
This method has no parameters.
|
| boolean |
This method will always return the correct
value in a single threaded environment,
but may return misleading results in
multithreaded, multiuser situations.. |
|
This method throws no exceptions.
|
Method atLast()
Returns TRUE if the iterator is positioned at the
end of the set of nodes it will iterate over.
|
This method has no parameters.
|
| boolean |
This method will always return the correct
value in a single threaded environment,
but may return misleading results in
multithreaded, multiuser situations.. |
|
This method throws no exceptions.
|
Method toNextNode()
This method returns the next node after the
"current" position and resets the current position
to be after the node returned.
|
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 toPrevNode()
This method returns the node before the
"current" position and resets the current position
to be before the node returned.
|
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 toFirstNode()
This method positions the iterator so that
the current position is just before the first node
in the set being iterated over.
|
This method has no parameters.
|
| Node |
Returns the first node in the set.
This method will only return
null when there are no items to
iterate over. |
|
This method throws no exceptions.
|
Method toLastNode()
This method positions the iterator so that the
current position is after the last node in the set being
iterated over.
|
This method has no parameters.
|
| Node |
Returns the last node in the set.
This method will only return
null when there are no items to
iterate over. |
|
This method throws no exceptions.
|
Method moveTo()
This method alters the internal state of
the iterator such that the current position is before the
Nth node in the sequence the iterator
is presenting relative to the current position.
Note: This may be a slow
operation.
| n | The index of the element in the set to
position the iterator before. |
| Node |
Returns the nth node. This method will return
null when position specified is out
of the range of legal values. |
|
This method throws no exceptions.
|
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(in int n) interface NoSuchNodeException {};
;
};
|
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.
| n | The index of the child to
position the iterator before. |
| 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.
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).
NOTE - In XML, the value of an attribute is represented by the
child nodes of an attribute node, since the value can be
and arbitrarily complex list of entity references. In HTML,
the value can only be a string; whether implementations must
expose this as Node is under discussion.
IDL Definition
interface Attribute {
wstring getName();
wstring getValue();
attribute boolean specified;
wstring toString();
};
|
Method getName()
Returns the name of this attribute.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
Method getValue()
Returns the string value of this attribute.
|
This method has no parameters.
|
|
This method throws no exceptions.
|
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 wit 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) interface NoSuchAttributeException {};
;
Attribute item(in unsigned long index) interface NoSuchAttributeException {};
;
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.
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.
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();
NodeIterator getAttributes();
wstring getAttribute(in name name);
void setAttribute(in string name,
in string value);
void removeAttribute(in wstring name);
Attribute getAttributeNode(in name name);
void setAttributeNode(in Attribute newAttr);
void removeAttributeNode(in Attribute oldAttr);
void getElementsByTagName(in wstring tagname);
void normalize();
};
|
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 getAttributes()
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 getAttribute()
Retrieves an Attribute value by name from an Element.
object.
| name | The name of the attribute to retrieve |
|
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 value
parameter.
|
This method throws no exceptions.
|
Method removeAttribute()
Removes the specified attribute from an Element node
object.
|
This method throws no exceptions.
|
Method getAttributeNode()
Retrieves an Attribute node by name from an Element.
object.
| name | The name of the attribute to retrieve |
|
This method throws no exceptions.
|
Method setAttributeNode()
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 removeAttributeNode()
Removes the specified attribute/value pair from an Element node
object.
|
This method throws no exceptions.
|
Method getElementsByTagName()
Returns an iterator through all subordinate elements
with a given tag name.
| tagname | The name of the tag to match on |
|
This method throws no exceptions.
|
Method normalize()
Puts all Tet nodes in the sub-tree underneath this
Element into a "normal" form where only markup (e.g., tags,
comments, PIs, CDATASections, and
and entity references separates Text nodes.
|
This method has no parameters.
|
|
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 ?>.
2.9. IDL Interface definitions
This section contains the IDL definitions for the objects in
the core 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
.
interface DOM {
Document createDocument(in wstring type);
boolean hasFeature(in wstring feature);
};
interface DocumentContext {
attribute Document document;
};
interface DocumentFragment : Node {
attribute Document masterDoc;
};
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();
TreeIterator createTreeIterator(in Node node);
NodeIterator getElementsByTagName(in wstring tagname);
};
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) interface NotMyChildException {};
;
Node replaceChild(in Node newChild,
in Node oldChild) interface NotMyChildException {};
;
Node removeChild(in Node oldChild) interface NotMyChildException {};
;
};
interface NodeIterator {
unsigned long getLength();
unsigned long getCurrentPos();
boolean atFirst();
boolean atLast();
Node toNextNode();
Node toPrevNode();
Node toFirstNode();
Node toLastNode();
Node moveTo(in int n);
};
interface TreeIterator : NodeIterator {
unsigned long numChildren();
unsigned long numPreviousSiblings();
unsigned long numNextSiblings();
Node toParent();
Node toPreviousSibling();
Node toNextSibling();
Node toFirstChild();
Node toLastChild();
Node toNthChild(in int n) interface NoSuchNodeException {};
;
};
interface Attribute {
wstring getName();
wstring getValue();
attribute boolean specified;
wstring toString();
};
interface AttributeList {
Attribute getAttribute(in wstring attrName);
Attribute setAttribute(in Attribute attr);
Attribute remove(in wstring attrName) interface NoSuchAttributeException {};
;
Attribute item(in unsigned long index) interface NoSuchAttributeException {};
;
unsigned long getLength();
};
interface Element : Node {
wstring getTagName();
NodeIterator getAttributes();
wstring getAttribute(in name name);
void setAttribute(in string name,
in string value);
void removeAttribute(in wstring name);
Attribute getAttributeNode(in name name);
void setAttributeNode(in Attribute newAttr);
void removeAttributeNode(in Attribute oldAttr);
void getElementsByTagName(in wstring tagname);
void normalize();
};
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);
};
interface Comment : Node {
attribute wstring data;
};
interface PI : Node {
attribute wstring name;
attribute wstring data;
};
|
2.10. Java Core API definitions
public interface DOM {
public Document createDocument(String type);
public boolean hasFeature(String feature);
}
public interface DocumentContext {
public Document getDocument();
public void setDocument(Document arg);
}
public interface DocumentFragment extends Node {
public Document getMasterDoc();
public void setMasterDoc(Document arg);
}
public interface Document extends DocumentFragment {
public Node getDocumentType();
public void setDocumentType(Node arg);
public Element getDocumentElement();
public void setDocumentElement(Element arg);
public DocumentContext getContextInfo();
public void setContextInfo(DocumentContext arg);
public DocumentContext createDocumentContext();
public Element createElement(String tagName,
AttributeList attributes);
public Text createTextNode(String data);
public Comment createComment(String data);
public PI createPI(String name,
String data);
public Attribute createAttribute(String name,
Node value);
public AttributeList createAttributeList();
public TreeIterator createTreeIterator(Node node);
public NodeIterator getElementsByTagName(String tagname);
}
public interface Node {
// NodeType
public static final int DOCUMENT = 1;
public static final int ELEMENT = 2;
public static final int ATTRIBUTE = 3;
public static final int PI = 4;
public static final int COMMENT = 5;
public static final int TEXT = 6;
public int getNodeType();
public Node getParentNode();
public NodeIterator getChildNodes();
public boolean hasChildNodes();
public Node getFirstChild();
public Node getPreviousSibling();
public Node getNextSibling();
public Node insertBefore(Node newChild,
Node refChild) public class NotMyChildException extends Exception {};
;
public Node replaceChild(Node newChild,
Node oldChild) public class NotMyChildException extends Exception {};
;
public Node removeChild(Node oldChild) public class NotMyChildException extends Exception {};
;
}
public interface NodeIterator {
public int getLength();
public int getCurrentPos();
public boolean atFirst();
public boolean atLast();
public Node toNextNode();
public Node toPrevNode();
public Node toFirstNode();
public Node toLastNode();
public Node moveTo(int n);
}
public interface TreeIterator extends NodeIterator {
public int numChildren();
public int numPreviousSiblings();
public int numNextSiblings();
public Node toParent();
public Node toPreviousSibling();
public Node toNextSibling();
public Node toFirstChild();
public Node toLastChild();
public Node toNthChild(int n) public class NoSuchNodeException extends Exception {};
;
}
public interface Attribute {
public String getName();
public String getValue();
public boolean getSpecified();
public void setSpecified(boolean arg);
public String toString();
}
public interface AttributeList {
public Attribute getAttribute(String attrName);
public Attribute setAttribute(Attribute attr);
public Attribute remove(String attrName) public class NoSuchAttributeException extends Exception {};
;
public Attribute item(int index) public class NoSuchAttributeException extends Exception {};
;
public int getLength();
}
public interface Element extends Node {
public String getTagName();
public NodeIterator getAttributes();
public String getAttribute(name name);
public void setAttribute(String name,
String value);
public void removeAttribute(String name);
public Attribute getAttributeNode(name name);
public void setAttributeNode(Attribute newAttr);
public void removeAttributeNode(Attribute oldAttr);
public void getElementsByTagName(String tagname);
public void normalize();
}
public interface Text extends Node {
public String getData();
public void setData(String arg);
public void append(String data);
public void insert(int offset,
String data);
public void delete(int offset,
int count);
public void replace(int offset,
int count,
String data);
public void splice(Element element,
int offset,
int count);
}
public interface Comment extends Node {
public String getData();
public void setData(String arg);
}
public interface PI extends Node {
public String getName();
public void setName(String arg);
public String getData();
public void setData(String arg);
}
|
2.11. ECMAScript Core API definitions
Object DOM
The DOM object has the following methods:
- createDocument(type)
- This method returns a Document.
The type parameter is expected to be of type wstring..
- hasFeature(feature)
- This method returns a boolean.
The feature parameter is expected to be of type wstring..
Object DocumentContext
The DocumentContext object has the following properties:
- document
- This property is expected to be a Document
Object DocumentFragment
DocumentFragment has the all the properties and methods of Node as well as the properties and methods defined below.
The DocumentFragment object has the following properties:
- masterDoc
- This property is expected to be a Document
Object Document
Document has the all the properties and methods of DocumentFragment as well as the properties and methods defined below.
The Document object has the following properties:
- documentType
- This property is expected to be a Node
- documentElement
- This property is expected to be a Element
- contextInfo
- This property is expected to be a DocumentContext
- createDocumentContext
- This property is expected to be a DocumentContext
- createAttributeList
- This property is expected to be a AttributeList
The Document object has the following methods:
- createElement(tagName, attributes)
- This method returns a Element.
The tagName parameter is expected to be of type wstring..
The attributes parameter is expected to be of type AttributeList..
- createTextNode(data)
- This method returns a Text.
The data parameter is expected to be of type wstring..
- createComment(data)
- This method returns a Comment.
The data parameter is expected to be of type wstring..
- createPI(name, data)
- This method returns a PI.
The name parameter is expected to be of type wstring..
The data parameter is expected to be of type wstring..
- createAttribute(name, value)
- This method returns a Attribute.
The name parameter is expected to be of type wstring..
The value parameter is expected to be of type Node..
- createTreeIterator(node)
- This method returns a TreeIterator.
The node parameter is expected to be of type Node..
- getElementsByTagName(tagname)
- This method returns a NodeIterator.
The tagname parameter is expected to be of type wstring..
Object Node
The Node object has the following properties:
- nodeType
- This property is expected to be a int
- parentNode
- This property is expected to be a Node
- childNodes
- This property is expected to be a NodeIterator
- hasChildNodes
- This property is expected to be a boolean
- firstChild
- This property is expected to be a Node
- previousSibling
- This property is expected to be a Node
- nextSibling
- This property is expected to be a Node
The Node object has the following methods:
- insertBefore(newChild, refChild)
- This method returns a Node.
The newChild parameter is expected to be of type Node..
The refChild parameter is expected to be of type Node..
- replaceChild(newChild, oldChild)
- This method returns a Node.
The newChild parameter is expected to be of type Node..
The oldChild parameter is expected to be of type Node..
- removeChild(oldChild)
- This method returns a Node.
The oldChild parameter is expected to be of type Node..
Object NodeIterator
The NodeIterator object has the following properties:
- length
- This property is expected to be a unsigned long
- currentPos
- This property is expected to be a unsigned long
- atFirst
- This property is expected to be a boolean
- atLast
- This property is expected to be a boolean
- toNextNode
- This property is expected to be a Node
- toPrevNode
- This property is expected to be a Node
- toFirstNode
- This property is expected to be a Node
- toLastNode
- This property is expected to be a Node
The NodeIterator object has the following methods:
- moveTo(n)
- This method returns a Node.
The n parameter is expected to be of type int..
Object TreeIterator
TreeIterator has the all the properties and methods of NodeIterator as well as the properties and methods defined below.
The TreeIterator object has the following properties:
- numChildren
- This property is expected to be a unsigned long
- numPreviousSiblings
- This property is expected to be a unsigned long
- numNextSiblings
- This property is expected to be a unsigned long
- toParent
- This property is expected to be a Node
- toPreviousSibling
- This property is expected to be a Node
- toNextSibling
- This property is expected to be a Node
- toFirstChild
- This property is expected to be a Node
- toLastChild
- This property is expected to be a Node
The TreeIterator object has the following methods:
- toNthChild(n)
- This method returns a Node.
The n parameter is expected to be of type int..
Object Attribute
The Attribute object has the following properties:
- specified
- This property is expected to be a boolean
- name
- This property is expected to be a wstring
- value
- This property is expected to be a wstring
- toString
- This property is expected to be a wstring
The Attribute object has the following methods:
Object AttributeList
The AttributeList object has the following properties:
- length
- This property is expected to be a unsigned long
The AttributeList object has the following methods:
- getAttribute(attrName)
- This method returns a Attribute.
The attrName parameter is expected to be of type wstring..
- setAttribute(attr)
- This method returns a Attribute.
The attr parameter is expected to be of type Attribute..
- remove(attrName)
- This method returns a Attribute.
The attrName parameter is expected to be of type wstring..
- item(index)
- This method returns a Attribute.
The index parameter is expected to be of type unsigned long..
Object Element
Element has the all the properties and methods of Node as well as the properties and methods defined below.
The Element object has the following properties:
- tagName
- This property is expected to be a wstring
- attributes
- This property is expected to be a NodeIterator
- normalize
- This property is expected to be a void
The Element object has the following methods:
- getAttribute(name)
- This method returns a wstring.
The name parameter is expected to be of type name..
- setAttribute(name, value)
- This method returns a void.
The name parameter is expected to be of type string..
The value parameter is expected to be of type string..
- removeAttribute(name)
- This method returns a void.
The name parameter is expected to be of type wstring..
- getAttributeNode(name)
- This method returns a Attribute.
The name parameter is expected to be of type name..
- setAttributeNode(newAttr)
- This method returns a void.
The newAttr parameter is expected to be of type Attribute..
- removeAttributeNode(oldAttr)
- This method returns a void.
The oldAttr parameter is expected to be of type Attribute..
- getElementsByTagName(tagname)
- This method returns a void.
The tagname parameter is expected to be of type wstring..
Object Text
Text has the all the properties and methods of Node as well as the properties and methods defined below.
The Text object has the following properties:
- data
- This property is expected to be a String
The Text object has the following methods:
- append(data)
- This method returns a void.
The data parameter is expected to be of type wstring..
- insert(offset, data)
- This method returns a void.
The offset parameter is expected to be of type int..
The data parameter is expected to be of type wstring..
- delete(offset, count)
- This method returns a void.
The offset parameter is expected to be of type int..
The count parameter is expected to be of type int..
- replace(offset, count, data)
- This method returns a void.
The offset parameter is expected to be of type int..
The count parameter is expected to be of type int..
The data parameter is expected to be of type wstring..
- splice(element, offset, count)
- This method returns a void.
The element parameter is expected to be of type Element..
The offset parameter is expected to be of type int..
The count parameter is expected to be of type int..
Object Comment
Comment has the all the properties and methods of Node as well as the properties and methods defined below.
The Comment object has the following properties:
- data
- This property is expected to be a String
Object PI
PI has the all the properties and methods of Node as well as the properties and methods defined below.
The PI object has the following properties:
- name
- This property is expected to be a String
- data
- This property is expected to be a String