Checking in Sources/Docs of DOM Level 2 from :

http://www.w3.org/DOM/DOMTM


git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225913 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
dims committed 2001-06-01 11:15:37 +00:00
1 parent 7d5c881d20
commit 82b88df622
231 files changed
+66110

No files matched your search

+130
View File
@@ -0,0 +1,130 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Id$ -->
<div1 id="Changes">
<head>Changes</head>
<orglist role="editors">
<member>
<name>Arnaud Le Hors</name>
<affiliation>IBM</affiliation>
</member>
<member>
<name>Philippe Le H&eacute;garet</name>
<affiliation>W3C</affiliation>
</member>
</orglist>
<div2 id="DOMLevel1to2Changes">
<head>Changes between DOM Level 1 Core and DOM Level 2 Core</head>
<glist>
<gitem>
<label>OMG IDL</label>
<def><p>The DOM Level 2 specifications are now using Corba 2.3.1
instead of Corba 2.2.</p>
</def>
</gitem>
<gitem>
<label>Type <code>DOMString</code></label>
<def><p>The definition of <code>DOMString</code> in IDL is now a
<code>valuetype</code>.</p>
</def>
</gitem>
</glist>
<div3 id="DOMLevel1Changes">
<head>Changes to DOM Level 1 Core interfaces and exceptions</head>
<glist>
<gitem>
<label>Interface <code>Attr</code></label>
<def><p>The <code>Attr</code> interface has one new
attribute: <code>ownerElement</code>.</p>
</def>
</gitem>
<gitem>
<label>Interface <code>Document</code></label>
<def><p>The <code>Document</code> interface has five new methods:
<code>importNode</code>, <code>createElementNS</code>,
<code>createAttributeNS</code>, <code>getElementsByTagNameNS</code>
and <code>getElementById</code>.</p>
</def>
</gitem>
<gitem>
<label>Interface <code>NamedNodeMap</code></label>
<def><p>The <code>NamedNodeMap</code> interface has three new
methods: <code>getNamedItemNS</code>, <code>setNamedItemNS</code>,
<code>removeNamedItemNS</code>.</p>
</def>
</gitem>
<gitem>
<label>Interface <code>Node</code></label>
<def><p>The <code>Node</code> interface has two new
methods: <code>isSupported</code> and <code>hasAttributes</code>.</p><p><code>normalize</code>, previously
in the <code>Element</code> interface, has been
moved in the <code>Node</code> interface.</p>
<p>The <code>Node</code> interface has three new attributes:
<code>namespaceURI</code>, <code>prefix</code> and
<code>localName</code>.</p>
<p>The <code>ownerDocument</code> attribute was specified to be
<code>null</code> when the node is a <code>Document</code>. It
now is also <code>null</code> when the node is a
<code>DocumentType</code> which is not used with any
<code>Document</code> yet.</p>
</def>
</gitem>
<gitem>
<label>Interface <code>DocumentType</code></label>
<def><p>The <code>DocumentType</code> interface has three attributes:
<code>publicId</code>, <code>systemId</code> and
<code>internalSubset</code>.</p>
</def>
</gitem>
<gitem>
<label>Interface <code>DOMImplementation</code></label>
<def><p>The <code>DOMImplementation</code> interface has two new
methods: <code>createDocumentType</code> and
<code>createDocument</code>.</p>
</def>
</gitem>
<gitem>
<label>Interface <code>Element</code></label>
<def><p>The <code>Element</code> interface has eight new
methods: <code>getAttributeNS</code>,
<code>setAttributeNS</code>, <code>removeAttributeNS</code>,
<code>getAttributeNodeNS</code>, <code>setAttributeNodeNS</code>,
<code>getElementsByTagNameNS</code>, <code>hasAttribute</code>
and <code>hasAttributeNS</code>.</p>
<p>The method <code>normalize</code> is now inherited from
the <code>Node</code> interface where it was moved.</p>
</def>
</gitem>
<gitem>
<label>Exception <code>DOMException</code></label>
<def><p>The <code>DOMException</code> has five new
exception codes: <code>INVALID_STATE_ERR</code>,
<code>SYNTAX_ERR</code>, <code>INVALID_MODIFICATION_ERR</code>,
<code>NAMESPACE_ERR</code> and <code>INVALID_ACCESS_ERR</code>.</p>
</def>
</gitem>
</glist>
</div3>
<div3 id="DOMLevel2Addons">
<head>New features</head>
<div4 id='DOMLevel2Addons-types'>
<head>New types</head>
<glist>
<gitem>
<label><code>DOMTimeStamp</code></label>
<def>
<p>
The <code>DOMTimeStamp</code> type was added to the Core
module.
</p>
</def>
</gitem>
</glist>
</div4>
</div3>
</div2>
</div1>
+383
View File
@@ -0,0 +1,383 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date$ $Revision$ -->
<!--
*************************************************************************
* BEGINNING OF CORE *
*************************************************************************
-->
<div1 id="Core">
<head>Document Object Model Core</head>
<orglist role="editors">
<member>
<name>Arnaud Le Hors</name>
<affiliation>IBM</affiliation>
</member>
<member>
<name>Gavin Nicol</name>
<affiliation>Inso EPS (for DOM Level 1)</affiliation>
</member>
<member>
<name>Lauren Wood</name>
<affiliation>SoftQuad, Inc. (for DOM Level 1)</affiliation>
</member>
<member>
<name>Mike Champion</name>
<affiliation>ArborText (for DOM Level 1 from November 20,
1997)</affiliation>
</member>
<member>
<name>Steve Byrne</name>
<affiliation>JavaSoft (for DOM Level 1 until November 19,
1997)</affiliation>
</member>
</orglist> <?GENERATE-MINI-TOC?>
<!--
******************************************************
| INTRODUCTION |
******************************************************
-->
<div2 id="ID-1590626201">
<head>Overview of the DOM Core Interfaces</head>
<p>This section defines a set of objects and interfaces for accessing and
manipulating document objects. The functionality specified in this section (the
<emph>Core</emph> functionality) is sufficient to allow software developers and
web script authors to access and manipulate parsed HTML and XML content inside
conforming products. The DOM Core API also allows creation and population of a <code>Document</code> object using only DOM API calls; loading a <code>Document</code> and saving it persistently is left to the product that implements the
DOM API.</p>
<div3 id="ID-1590626202"><head>The DOM Structure Model</head>
<p>The DOM presents documents as a hierarchy of <code>Node</code> objects that also implement other, more specialized interfaces. Some
types of nodes may have <termref def="dt-child">child</termref> nodes of
various types, and others are leaf nodes that cannot have anything below them
in the document structure. For XML and HTML, the node types, and which node
types they may have as children, are as follows:
<ulist>
<item>
<p><code>Document</code> -- <code>Element</code> (maximum of one), <code>ProcessingInstruction</code>, <code>Comment</code>, <code>DocumentType</code> (maximum of one) </p>
</item>
<item>
<p><code>DocumentFragment</code> -- <code>Element</code>, <code>ProcessingInstruction</code>, <code>Comment</code>, <code>Text</code>, <code>CDATASection</code>, <code>EntityReference</code> </p>
</item>
<item>
<p><code>DocumentType</code> -- no children</p>
</item>
<item>
<p><code>EntityReference</code> -- <code>Element</code>, <code>ProcessingInstruction</code>, <code>Comment</code>, <code>Text</code>, <code>CDATASection</code>, <code>EntityReference</code> </p>
</item>
<item>
<p><code>Element</code> -- <code>Element</code>, <code>Text</code>, <code>Comment</code>, <code>ProcessingInstruction</code>, <code>CDATASection</code>, <code>EntityReference</code></p>
</item>
<item>
<p><code>Attr</code> -- <code>Text</code>, <code>EntityReference</code></p>
</item>
<item>
<p><code>ProcessingInstruction</code> -- no children</p>
</item>
<item>
<p><code>Comment</code> -- no children</p>
</item>
<item>
<p><code>Text</code> -- no children</p>
</item>
<item>
<p><code>CDATASection</code> -- no children</p>
</item>
<item>
<p><code>Entity</code> -- <code>Element</code>, <code>ProcessingInstruction</code>, <code>Comment</code>, <code>Text</code>, <code>CDATASection</code>, <code>EntityReference</code></p>
</item>
<item>
<p><code>Notation</code> -- no children</p>
</item>
</ulist> </p>
<p>The DOM also specifies a <code>NodeList</code> interface to handle ordered lists of <code>Nodes</code>, such as the children of a <code>Node</code>, or the <termref def="dt-element">elements</termref> returned by the <code>getElementsByTagName</code> method of the <code>Element</code> interface, and also a <code>NamedNodeMap</code> interface to handle unordered sets of nodes referenced by their name
attribute, such as the attributes of an <code>Element</code>. <termdef id="td-live" term="live"> <code>NodeList</code> and <code>NamedNodeMap</code> objects in the DOM are <term>live</term>; that is, changes to the
underlying document structure are reflected in all relevant <code>NodeList</code> and <code>NamedNodeMap</code> objects. For example, if a DOM user gets a <code>NodeList</code> object containing the children of an <code>Element</code>, then subsequently adds more children to that <termref
def="dt-element">element</termref> (or removes children, or modifies them),
those changes are automatically reflected in the <code>NodeList</code>, without further action on the user's part. Likewise, changes to a <code>Node</code> in the tree are reflected in all references to that <code>Node</code> in <code>NodeList</code> and <code>NamedNodeMap</code> objects.</termdef></p>
<p>Finally, the interfaces <code>Text</code>, <code>Comment</code>, and <code>CDATASection</code> all inherit from the <code>CharacterData</code> interface.</p>
</div3>
<div3 id="ID-249F15BA"><head>Memory Management</head>
<p>Most of the APIs defined by this specification are
<emph>interfaces</emph> rather than classes. That means that an implementation
need only expose methods with the defined names and specified operation, not
implement classes that correspond directly to the interfaces. This allows the
DOM APIs to be implemented as a thin veneer on top of legacy applications with
their own data structures, or on top of newer applications with different class
hierarchies. This also means that ordinary constructors (in the Java or C++
sense) cannot be used to create DOM objects, since the underlying objects to be
constructed may have little relationship to the DOM interfaces. The
conventional solution to this in object-oriented design is to define
<emph>factory</emph> methods that create instances of objects that implement
the various interfaces. Objects implementing some interface "X" are created by
a "createX()" method on the <code>Document</code> interface; this is because all DOM objects live in the context of a
specific Document.</p>
<p>The DOM Level 2 API does <emph>not</emph> define a standard way to
create <code>DOMImplementation</code> objects; DOM implementations must provide some proprietary way of
bootstrapping these DOM interfaces, and then all other objects can be built
from there.</p>
<p>The Core DOM APIs are designed to be compatible with a wide range of
languages, including both general-user scripting languages and the more
challenging languages used mostly by professional programmers. Thus, the DOM
APIs need to operate across a variety of memory management philosophies, from
language bindings that do not expose memory management to the user at all,
through those (notably Java) that provide explicit constructors but provide an
automatic garbage collection mechanism to automatically reclaim unused memory,
to those (especially C/C++) that generally require the programmer to explicitly
allocate object memory, track where it is used, and explicitly free it for
re-use. To ensure a consistent API across these platforms, the DOM does not
address memory management issues at all, but instead leaves these for the
implementation. Neither of the explicit language bindings defined by the DOM
API (for <termref def="dt-ECMAScript">ECMAScript</termref> and Java)
require any memory management methods, but DOM bindings for other languages
(especially C or C++) may require such support. These extensions will be the
responsibility of those adapting the DOM API to a specific language, not the
DOM Working Group. </p>
</div3>
<div3 id="ID-45A944CB">
<head>Naming Conventions</head>
<p>While it would be nice to have attribute and method names that are
short, informative, internally consistent, and familiar to users of similar
APIs, the names also should not clash with the names in legacy APIs supported
by DOM implementations. Furthermore, both OMG IDL and <code>ECMAScript</code> have significant limitations in their ability to disambiguate names
from different namespaces that make it difficult to avoid naming conflicts with
short, familiar names. So, DOM names tend to be long and descriptive
in order to be unique across all environments. </p>
<p>The Working Group has also attempted to be internally consistent in
its use of various terms, even though these may not be common distinctions in
other APIs. For example, the DOM API uses the method name "remove" when the method
changes the structural model, and the method name "delete" when the method gets
rid of something inside the structure model. The thing that is deleted is not
returned. The thing that is removed may be returned, when it makes sense to
return it. </p>
</div3>
<div3 id="ID-1CED5498">
<head>Inheritance vs. Flattened Views of the API</head>
<p>The DOM Core <termref def="dt-API">APIs</termref> present two somewhat
different sets of interfaces to an XML/HTML document: one presenting an "object
oriented" approach with a hierarchy of <termref
def="dt-inheritance">inheritance</termref>, and a "simplified" view that allows
all manipulation to be done via the <code>Node</code> interface without requiring casts (in Java and other C-like languages)
or query interface calls in <termref def="dt-COM">COM</termref> environments.
These operations are fairly expensive in Java and COM, and the DOM may be used
in performance-critical environments, so we allow significant functionality
using just the <code>Node</code> interface. Because many other users will find the
<termref def="dt-inheritance">inheritance</termref> hierarchy easier to
understand than the "everything is a <code>Node</code>" approach to the DOM, we also support the full higher-level interfaces
for those who prefer a more object-oriented <termref
def="dt-API">API</termref>. </p>
<p>In practice, this means that there is a certain amount of redundancy
in the <termref def="dt-API">API</termref>. The Working Group considers the
"<termref def="dt-inheritance">inheritance</termref>" approach the primary view
of the API, and the full set of functionality on <code>Node</code> to be "extra" functionality that users may employ, but that does not
eliminate the need for methods on other interfaces that an object-oriented
analysis would dictate. (Of course, when the O-O analysis yields an attribute
or method that is identical to one on the <code>Node</code> interface, we don't specify a completely redundant one.) Thus, even
though there is a generic <code>nodeName</code> attribute on the <code>Node</code> interface, there is still a <code>tagName</code> attribute on the <code>Element</code> interface; these two attributes must contain the same value, but the
it is worthwhile to support both, given the different
constituencies the DOM <termref def="dt-API">API</termref> must satisfy. </p>
</div3>
<div3 id="ID-C74D1578">
<head>The <code>DOMString</code> type</head>
<p>To ensure interoperability, the DOM specifies the following:</p>
<ulist>
<item>
<definitions>
<typedef name="DOMString" id="DOMString">
<descr>
<p>A <code>DOMString</code> is a sequence of <termref def="dt-16-bit-unit">16-bit
units</termref>.</p>
</descr>
<sequence type="unsigned short"/>
</typedef>
</definitions>
</item>
<item>
<p>Applications must encode <code>DOMString</code> using UTF-16 (defined in <bibref ref="Unicode"/> and Amendment 1 of
<bibref ref="ISO10646"/>).</p>
<p>The UTF-16 encoding was chosen because of its widespread industry
practice. Note that for both HTML and XML, the document character set (and
therefore the notation of numeric character references) is based on UCS
[ISO-10646]. A single numeric character reference in a source document may
therefore in some cases correspond to two 16-bit units in a <code>DOMString</code> (a high surrogate and a low surrogate).</p>
<note>
<p>Even though the DOM defines the name of the string type to be <code>DOMString</code>, bindings may use different names. For example for Java, <code>DOMString</code> is bound to the <code>String</code> type because it also uses UTF-16 as its encoding.</p>
</note>
</item>
</ulist>
<note>
<p>As of August 2000, the OMG IDL specification (<bibref
ref="OMGIDL"/>) included a <code>wstring</code> type. However, that definition did not meet the interoperability
criteria of the DOM <termref def="dt-API">API</termref> since it relied on
negotiation to decide the width and encoding of a character.</p>
</note>
</div3>
<div3 id="Core-DOMTimeStamp">
<head>The <code>DOMTimeStamp</code> type</head>
<p>To ensure interoperability, the DOM specifies the following:</p>
<ulist>
<item>
<definitions>
<typedef name="DOMTimeStamp" id="DOMTimeStamp">
<descr>
<p> A <code>DOMTimeStamp</code> represents a number of milliseconds. </p>
</descr>
<typename>unsigned long long</typename>
</typedef>
</definitions>
</item>
<item>
<note>
<p> Even though the DOM uses the type <code>DOMTimeStamp</code>, bindings may use different types. For example for Java, <code>DOMTimeStamp</code> is bound to the <code>long</code> type. In ECMAScript, <code>TimeStamp</code> is bound to the <code>Date</code> type because the range of the <code>integer</code> type is too small. </p>
</note>
</item>
</ulist>
</div3>
<div3 id="ID-5DFED1F0">
<head>String comparisons in the DOM</head>
<p>The DOM has many interfaces that imply string matching. HTML
processors generally assume an uppercase (less often, lowercase) normalization
of names for such things as <termref def="dt-element">elements</termref>, while
XML is explicitly case sensitive. For the purposes of the DOM, string matching
is performed purely by binary <termref
def="dt-string-compare">comparison</termref> of the
<termref def="dt-16-bit-unit">16-bit units</termref> of the <code>DOMString</code>. In addition, the DOM assumes that any case normalizations take place
in the processor, <emph>before</emph> the DOM structures are built.</p>
<note>
<p>Besides case folding, there are additional normalizations that can
be applied to text. The W3C I18N Working Group is in the process of defining
exactly which normalizations are necessary, and where they should be applied.
The W3C I18N Working Group expects to require early normalization, which means
that data read into the DOM is assumed to already be normalized. The DOM and
applications built on top of it in this case only have to assure that text
remains normalized when being changed. For further details, please see
<bibref ref="Charmod"/>.</p>
</note>
</div3>
<div3 id="Namespaces-Considerations">
<head>XML Namespaces</head>
<p>The DOM Level 2 supports XML namespaces <bibref ref="Namespaces"/> by
augmenting several interfaces of the DOM Level 1 Core to allow creating and
manipulating <termref def="dt-element">elements</termref> and attributes
associated to a namespace.</p>
<p>As far as the DOM is concerned, special attributes used for declaring
<termref def="dt-XML-namespace">XML namespaces</termref> are still exposed and
can be manipulated just like any other attribute. However, nodes are
permanently bound to <termref def="dt-namespaceURI">namespace URIs</termref> as
they get created. Consequently, moving a node within a document, using the DOM,
in no case results in a change of its <termref
def="dt-namespaceprefix">namespace prefix</termref> or namespace URI.
Similarly, creating a node with a namespace prefix and namespace URI, or
changing the namespace prefix of a node, does not result in any addition,
removal, or modification of any special attributes for declaring the
appropriate XML namespaces. Namespace validation is not enforced; the DOM
application is responsible. In particular, since the mapping between prefixes
and namespace URIs is not enforced, in general, the resulting document cannot
be serialized naively. For example, applications may have to declare every
namespace in use when serializing a document.</p>
<p>DOM Level 2 doesn't perform any URI normalization or canonicalization.
The URIs given to the DOM are assumed to be valid (e.g., characters such as
whitespaces are properly escaped), and no lexical checking is performed.
Absolute URI references are treated as strings and
<termref def="dt-string-compare">compared literally</termref>. How relative
namespace URI references are treated is undefined. To ensure interoperability
only absolute namespace URI references (i.e., URI references beginning with a
scheme name and a colon) should be used. Note that because the DOM does no
lexical checking, the empty string will be treated as a real namespace URI
in DOM Level 2 methods. Applications must use the value <code>null</code>
as the namespaceURI parameter for methods if they wish to have no
namespace.</p>
<note>
<p>In the DOM, all namespace declaration attributes are <emph>by
definition</emph> bound to the namespace URI: "<loc
href="&xmlns-ns;">&xmlns-ns;</loc>". These are the attributes whose
<termref def="dt-namespaceprefix">namespace prefix</termref> or
<termref def="dt-qualifiedname">qualified name</termref> is "xmlns". Although,
at the time of writing, this is not part of the XML Namespaces specification
<bibref ref="Namespaces"/>, it is planned to be incorporated in a future
revision.</p>
</note>
<p>In a document with no namespaces, the <termref
def="dt-child">child</termref> list of an <code>EntityReference</code> node is always the same as that of the corresponding <code>Entity</code>. This is not true in a document where an entity contains unbound
<termref def="dt-namespaceprefix">namespace prefixes</termref>. In such a case,
the <termref def="dt-descendant">descendants</termref> of the corresponding <code>EntityReference</code> nodes may be bound to different <termref
def="dt-namespaceURI">namespace URIs</termref>, depending on where the entity
references are. Also, because, in the DOM, nodes always remain bound to the
same namespace URI, moving such <code>EntityReference</code> nodes can lead to documents that cannot be serialized. This is also
true when the DOM Level 1 method <code>createEntityReference</code> of the <code>Document</code> interface is used to create entity references that correspond to such
entities, since the <termref def="dt-descendant">descendants</termref> of the
returned <code>EntityReference</code> are unbound. The DOM Level 2 does not support any mechanism to resolve
namespace prefixes. For all of these reasons, use of such entities and entity
references should be avoided or used with extreme care. A future Level of the
DOM may include some additional support for handling these.</p>
<p>The new methods, such as <code>createElementNS</code> and <code>createAttributeNS</code> of the <code>Document</code> interface, are meant to be used by namespace aware applications. Simple
applications that do not use namespaces can use the DOM Level 1 methods, such
as <code>createElement</code> and <code>createAttribute</code>. Elements and attributes created in this way do not have any namespace
prefix, namespace URI, or local name.</p>
<note>
<p>DOM Level 1 methods are namespace ignorant. Therefore, while it is
safe to use these methods when not dealing with namespaces, using them and the
new ones at the same time should be avoided. DOM Level 1 methods solely
identify attribute nodes by their <code>nodeName</code>. On the contrary, the DOM Level 2 methods related to namespaces,
identify attribute nodes by their <code>namespaceURI</code> and <code>localName</code>. Because of this fundamental difference, mixing both sets of methods
can lead to unpredictable results. In particular, using <code>setAttributeNS</code>, an <termref def="dt-element">element</termref> may have two attributes
(or more) that have the same <code>nodeName</code>, but different <code>namespaceURI</code>s. Calling <code>getAttribute</code> with that <code>nodeName</code> could then return any of those attributes. The result depends on the
implementation. Similarly, using <code>setAttributeNode</code>, one can set two attributes (or more) that have different <code>nodeNames</code> but the same <code>prefix</code> and <code>namespaceURI</code>. In this case <code>getAttributeNodeNS</code> will return either attribute, in an implementation dependent manner.
The only guarantee in such cases is that all methods that access a named item
by its <code>nodeName</code> will access the same item, and all methods which access a node by its
URI and local name will access the same node. For instance, <code>setAttribute</code> and <code>setAttributeNS</code> affect the node that <code>getAttribute</code> and <code>getAttributeNS</code>, respectively, return.</p>
</note>
</div3>
</div2> <!--
******************************************************
| DOCUMENT OBJECT MODEL APIs |
******************************************************
-->
<div2 id="ID-BBACDC08">
<head>Fundamental Interfaces</head>
<p>The interfaces within this section are considered
<emph>fundamental</emph>, and must be fully implemented by all conforming
implementations of the DOM, including all HTML DOM implementations
<bibref ref="DOMHTML-inf"/>, unless otherwise specified.
</p>
<p>
A DOM application may use the <code>hasFeature(feature,
version)</code> method of the <code>DOMImplementation</code>
interface with parameter values "Core" and "2.0" (respectively) to
determine whether or not this module is supported by the
implementation. Any implementation that conforms to DOM Level 2 or a
DOM Level 2 module must conform to the Core module. Please refer to
additional information about <xspecref
href='&core.latest.url;/introduction.html#ID-Conformance'>conformance</xspecref>
in this specification.
</p>
<definitions> &exceptions; &core-dom; &core-document; &core-node;
&core-node-list; &core-named-node-map; &core-data; &core-attribute;
&core-element; &core-text; &core-comment;
</definitions>
</div2>
<div2 id="ID-E067D597">
<head>Extended Interfaces</head>
<p>The interfaces defined here form part of the DOM Core specification, but
objects that expose these interfaces will never be encountered in a DOM
implementation that deals only with HTML. As such, HTML-only DOM
implementations <bibref ref="DOMHTML-inf"/> do not need to have objects that
implement these interfaces.</p>
<p>
The interfaces found within this section are not mandatory. A DOM
application may use the <code>hasFeature(feature, version)</code> method
of the <code>DOMImplementation</code> interface with parameter values
"XML" and "2.0" (respectively) to determine whether or not this module
is supported by the implementation. In order to fully support this
module, an implementation must also support the "Core" feature defined in
<specref ref="ID-BBACDC08"/>. Please refer to additional information about
<specref ref='ID-Conformance'/> in this specification.
</p>
<definitions> &core-cdata-section; &core-doctype; &core-notation;
&core-entity; &core-entity-reference; &core-pi;
</definitions>
</div2></div1><!--
*************************************************************************
* END OF CORE *
*************************************************************************
-->
@@ -0,0 +1,113 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date$ $Revision$ -->
<!--[ Attr object description ]-->
<interface name="Attr" inherits="Node" id="ID-637646024">
<descr><p>
The <code>Attr</code> interface represents an attribute in an <code>Element</code> object.
Typically the allowable values for the attribute are defined in a document
type definition.</p>
<p><code>Attr</code> objects inherit the <code>Node</code>
interface, but since they are not actually child nodes of the element
they describe, the DOM does not consider them part of the document
tree. Thus, the <code>Node</code> attributes <code>parentNode</code>,
<code>previousSibling</code>, and <code>nextSibling</code> have a
<code>null</code> value for <code>Attr</code> objects. The DOM takes the
view that attributes are properties of elements rather than having a
separate identity from the elements they are associated with;
this should make it more efficient to implement
such features as default attributes associated with all elements of a
given type. Furthermore, <code>Attr</code>
nodes may not be immediate children of a <code>DocumentFragment</code>.
However, they can be associated with <code>Element</code> nodes contained within
a <code>DocumentFragment</code>.
In short, users and implementors of the DOM need to be aware that
<code>Attr</code> nodes have some things in
common with other objects inheriting the <code>Node</code> interface,
but they also are quite distinct.</p>
<p> 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 does not exist on this element in the structure model until
it has been explicitly added. Note that the <code>nodeValue</code>
attribute on the <code>Attr</code> instance can also be used to
retrieve the string version of the attribute's value(s). </p>
<p>In XML, where the value of an attribute can contain entity references,
the child nodes of the <code>Attr</code> node may be either
<code>Text</code> or <code>EntityReference</code> nodes (when these are in
use; see the description of <code>EntityReference</code> for
discussion). Because the DOM Core is not aware of attribute types, it
treats all attribute values as simple strings, even if the DTD or schema
declares them as having <termref def="dt-tokenized">tokenized</termref>
types.
</p>
</descr>
<attribute type="DOMString" readonly="yes" name="name" id="ID-1112119403">
<descr><p>Returns the name of this attribute. </p></descr>
</attribute>
<attribute type="boolean" readonly="yes" name="specified" id="ID-862529273">
<descr><p>If this attribute was explicitly given a value in the original
document, this is <code>true</code>; otherwise, it is <code>false</code>.
Note that the implementation is in charge of this attribute, not the
user. If the user changes the value of the attribute (even if it ends up
having the same value as the default value) then the <code>specified</code>
flag is automatically flipped to <code>true</code>. To re-specify the
attribute as the default value from the DTD, the user must delete the
attribute. The implementation will then make a new attribute available
with <code>specified</code> set to <code>false</code> and the default value
(if one exists).</p>
<p>In summary:
<ulist>
<item><p> If the attribute has an assigned value in the document then
<code>specified</code> is <code>true</code>, and the value is the
assigned value.
</p></item>
<item><p> If the attribute has no assigned value in the document and has
a default value in the DTD, then <code>specified</code> is <code>false</code>,
and the value is the default value in the DTD.</p></item>
<item><p> If the attribute has no assigned value in the document and has
a value of #IMPLIED in the DTD, then the attribute does not appear
in the structure model of the document.
</p></item>
<item><p>If the <code>ownerElement</code> attribute is
<code>null</code> (i.e. because it was just created or was set to
<code>null</code> by the various removal and cloning operations)
<code>specified</code> is <code>true</code>.</p>
</item>
</ulist>
</p>
</descr>
</attribute>
<attribute type="DOMString" name="value" id="ID-221662474">
<descr><p>On retrieval, the value of the attribute is returned as a
string. Character and general entity references are replaced with their
values. See also the method <code>getAttribute</code> on the
<code>Element</code> interface.</p>
<p>On setting, this creates a <code>Text</code> node with the unparsed
contents of the string. I.e. any characters that an XML processor would
recognize as markup are instead treated as literal text.
See also the method <code>setAttribute</code> on the
<code>Element</code> interface.</p></descr>
<setraises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised when the node is
readonly.</p></descr>
</exception>
</setraises>
</attribute>
<!-- ****** DOM Level 2 additions ****** -->
<attribute name="ownerElement" type="Element" readonly="yes"
id="Attr-ownerElement" since="DOM Level 2">
<descr><p>The <code>Element</code> node this attribute is attached to or
<code>null</code> if this attribute is not in use.</p></descr>
</attribute>
</interface>
@@ -0,0 +1,39 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ CDATA Section ]-->
<!-- $Date$ $Revision$ -->
<interface name="CDATASection" inherits="Text" id="ID-667469212">
<descr><p>CDATA sections are used to escape blocks of text containing
characters that would otherwise be regarded as markup. The only
delimiter that is recognized in a CDATA section is the "]]&gt;" string
that ends the CDATA section. CDATA sections cannot be
nested. Their primary purpose is for including
material such as XML fragments, without needing to escape all
the delimiters.</p><p>The <code>DOMString</code> attribute of the
<code>Text</code> node holds the text that is contained by the CDATA
section. Note that this <emph>may</emph> contain characters
that need to be escaped outside of CDATA sections and that, depending on
the character encoding ("charset") chosen for serialization, it may be
impossible to write out some characters as part of a CDATA section. </p>
<p> The <code>CDATASection</code> interface inherits from the
<code>CharacterData</code> interface through the <code>Text</code>
interface. Adjacent <code>CDATASection</code> nodes are not merged by
use of the <code>normalize</code> method of the <code>Node</code>
interface.</p>
<note>
<p>Because no markup is recognized within a <code>CDATASection</code>,
character numeric references cannot be used as an escape mechanism
when serializing. Therefore, action needs to be taken when serializing
a <code>CDATASection</code> with a character encoding where some of
the contained characters cannot be represented. Failure to do so would
not produce well-formed XML.</p>
<p>One potential solution in the serialization process is to end the
CDATA section before the character, output the character using a
character reference or entity reference, and open a new CDATA section
for any further characters in the text node. Note, however, that some
code conversion libraries at the time of writing do not return an
error or exception when a character is missing from the encoding,
making the task of ensuring that data is not corrupted on serialization
more difficult.</p>
</note>
</descr>
</interface>
@@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ Comment object description ]-->
<!-- $Date$ $Revision$ -->
<interface name="Comment" inherits="CharacterData" id="ID-1728279322">
<descr><p>This interface inherits from <code>CharacterData</code> and
represents the content of a comment, i.e., all the
characters between the starting '<code>&lt;!--</code>' and
ending '<code>--&gt;</code>'. 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.</p></descr>
</interface>
+195
View File
@@ -0,0 +1,195 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ Data interface description ]-->
<!-- $Date$ $Revision$ -->
<interface name="CharacterData" inherits="Node" id="ID-FF21A306">
<descr><p>The <code>CharacterData</code> interface extends Node with a set of
attributes and methods for accessing character data in the DOM. For
clarity this set is defined here rather than on each object that uses
these attributes and methods. No DOM objects correspond directly to
<code>CharacterData</code>, though <code>Text</code> and others do
inherit the interface from it. All <code>offsets</code> in this
interface start from <code>0</code>.</p>
<p>As explained in the <code>DOMString</code> interface, text strings
in the DOM are represented in UTF-16, i.e. as a sequence of 16-bit
units. In the following, the term <termref
def='dt-16-bit-unit'>16-bit units</termref> is used whenever
necessary to indicate that indexing on CharacterData is done in
16-bit units.</p>
</descr>
<attribute type="DOMString" name="data" id="ID-72AB8359">
<descr><p>The character data of the node
that implements this interface. The DOM implementation may not
put arbitrary limits on the amount of data that may be stored in a
<code>CharacterData</code> node. However, implementation limits may
mean that the entirety of a node's data may not fit into a single
<code>DOMString</code>. In such cases, the user may call
<code>substringData</code> to retrieve the data in appropriately sized
pieces.</p>
</descr>
<setraises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised when the node is
readonly.</p></descr>
</exception>
</setraises>
<getraises>
<exception name="DOMException">
<descr><p>DOMSTRING_SIZE_ERR: Raised when it would return more
characters than fit in a <code>DOMString</code> variable on the
implementation platform.</p></descr>
</exception>
</getraises>
</attribute>
<attribute type="unsigned long" name="length" readonly="yes" id="ID-7D61178C">
<descr><p>The number of <termref def='dt-16-bit-unit'>16-bit
units</termref> that are available through <code>data</code> and the
<code>substringData</code> method below. This may have the value zero,
i.e., <code>CharacterData</code> nodes may be empty.</p>
</descr>
</attribute>
<method name="substringData" id="ID-6531BCCF">
<descr><p>Extracts a range of data from the node.</p></descr>
<parameters>
<param name="offset" type="unsigned long" attr="in">
<descr><p>Start offset of substring to extract.</p></descr>
</param>
<param name="count" type="unsigned long" attr="in">
<descr><p>The number of 16-bit units to extract.</p></descr>
</param>
</parameters>
<returns type="DOMString">
<descr><p>The specified substring. If the sum of <code>offset</code> and
<code>count</code> exceeds the <code>length</code>, then all 16-bit
units to the end of the data are returned.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INDEX_SIZE_ERR: Raised if the specified <code>offset</code>
is negative or greater than the number of 16-bit units in
<code>data</code>, or if the specified <code>count</code> is
negative.</p>
<p>DOMSTRING_SIZE_ERR: Raised if the specified range of text does
not fit into a <code>DOMString</code>.</p>
</descr>
</exception>
</raises>
</method>
<method name="appendData" id="ID-32791A2F">
<descr>
<p>Append the string to the end of the character data of the node.
Upon success, <code>data</code> provides access to the concatenation of
<code>data</code> and the <code>DOMString</code> specified.</p>
</descr>
<parameters>
<param name="arg" type="DOMString" attr="in">
<descr><p>The <code>DOMString</code> to append.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
readonly.</p></descr>
</exception>
</raises>
</method>
<!-- NOTE -->
<method name="insertData" id="ID-3EDB695F">
<descr>
<p>Insert a string at the specified <termref def='dt-16-bit-unit'>16-bit
unit</termref> offset.</p>
</descr>
<parameters>
<param name="offset" type="unsigned long" attr="in">
<descr><p>The character offset at which to insert.</p></descr>
</param>
<param name="arg" type="DOMString" attr="in">
<descr><p>The <code>DOMString</code> to insert.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INDEX_SIZE_ERR: Raised if the specified <code>offset</code>
is negative or greater than the number of 16-bit units in
<code>data</code>.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="deleteData" id="ID-7C603781">
<descr>
<p>Remove a range of <termref def='dt-16-bit-unit'>16-bit units</termref>
from the node. Upon success, <code>data</code> and <code>length</code>
reflect the change.</p>
</descr>
<parameters>
<param name="offset" type="unsigned long" attr="in">
<descr><p>The offset from which to start removing.</p>
</descr>
</param>
<param name="count" type="unsigned long" attr="in">
<descr><p>The number of 16-bit units to delete. If the sum of
<code>offset</code> and <code>count</code> exceeds
<code>length</code> then all 16-bit units from <code>offset</code>
to the end of the data are deleted.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INDEX_SIZE_ERR: Raised if the specified <code>offset</code>
is negative or greater than the number of 16-bit units in
<code>data</code>, or if the specified <code>count</code> is
negative.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="replaceData" id="ID-E5CBA7FB">
<descr>
<p>Replace the characters starting at the specified <termref
def='dt-16-bit-unit'>16-bit unit</termref> offset with the specified
string.</p>
</descr>
<parameters>
<param name="offset" type="unsigned long" attr="in">
<descr><p>The offset from which to start replacing.</p></descr>
</param>
<param name="count" type="unsigned long" attr="in">
<descr><p>The number of 16-bit units to replace. If the sum of
<code>offset</code> and <code>count</code> exceeds
<code>length</code>, then all 16-bit units to the end of the data
are replaced; (i.e., the effect is the same as a
<code>remove</code> method call with the same range, followed
by an <code>append</code> method invocation).</p></descr>
</param>
<param name="arg" type="DOMString" attr="in">
<descr><p>The <code>DOMString</code> with which the range must
be replaced.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INDEX_SIZE_ERR: Raised if the specified <code>offset</code>
is negative or greater than the number of 16-bit units in
<code>data</code>, or if the specified <code>count</code> is
negative.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
</descr>
</exception>
</raises>
</method>
</interface>
@@ -0,0 +1,65 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ DocumentType object description ]-->
<interface name="DocumentType" inherits="Node" id="ID-412266927">
<descr><p>Each <code>Document</code> has a <code>doctype</code> attribute
whose value is either <code>null</code> or a <code>DocumentType</code>
object. The <code>DocumentType</code> interface in the DOM Core
provides an interface to the list of entities that are defined
for the document, and little else because the effect of
namespaces and the various XML schema efforts on DTD
representation are not clearly understood as of this writing.</p>
<p>The DOM Level 2 doesn't support editing <code>DocumentType</code>
nodes.</p></descr>
<attribute readonly="yes" name="name" type="DOMString" id="ID-1844763134">
<descr><p>The name of DTD; i.e., the name immediately
following the <code>DOCTYPE</code> keyword.</p></descr>
</attribute>
<attribute readonly="yes" name="entities" type="NamedNodeMap" id="ID-1788794630">
<descr><p>A <code>NamedNodeMap</code> containing the general entities, both
external and internal, declared in the DTD. Parameter entities are not
contained. Duplicates are discarded.
For example in:
<eg role="code">&lt;!DOCTYPE ex SYSTEM "ex.dtd" [
&lt;!ENTITY foo "foo">
&lt;!ENTITY bar "bar">
&lt;!ENTITY bar "bar2">
&lt;!ENTITY % baz "baz">
]>
&lt;ex/></eg>
the interface provides access to <code>foo</code> and
the first declaration of <code>bar</code> but not the second declaration of
<code>bar</code> or <code>baz</code>. Every node in this map
also implements the <code>Entity</code> interface.</p>
<p>The DOM Level 2 does not support editing entities, therefore
<code>entities</code> cannot be altered in any way.</p>
</descr>
</attribute>
<attribute readonly="yes" name="notations" type="NamedNodeMap" id="ID-D46829EF">
<descr><p>A <code>NamedNodeMap</code> containing the
notations declared in the DTD. Duplicates are discarded. Every node in
this map also implements the <code>Notation</code> interface.</p>
<p>The DOM Level 2 does not support editing notations, therefore
<code>notations</code> cannot be altered in any way.</p></descr>
</attribute>
<!-- ****** DOM Level 2 additions ****** -->
<attribute readonly="yes" name="publicId" type="DOMString"
id="ID-Core-DocType-publicId" since="DOM Level 2">
<descr><p>The public identifier of the external subset.</p></descr>
</attribute>
<attribute readonly="yes" name="systemId" type="DOMString"
id="ID-Core-DocType-systemId" since="DOM Level 2">
<descr><p>The system identifier of the external subset.</p></descr>
</attribute>
<attribute readonly="yes" name="internalSubset" type="DOMString"
id="ID-Core-DocType-internalSubset" since="DOM Level 2">
<descr><p>The internal subset as a string.</p>
<note><p>The actual content returned depends on how much information is
available to the implementation. This may vary depending on various
parameters, including the XML processor used to build the
document.</p>
</note>
</descr>
</attribute>
</interface>
@@ -0,0 +1,607 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ DocumentFragment object description ]-->
<!-- $Date$ $Revision$ -->
<interface name="DocumentFragment" inherits="Node" id="ID-B63ED1A3">
<descr><p><code>DocumentFragment</code> is a "lightweight" or "minimal"
<code>Document</code> object. It is very common to want to be able to
extract a portion of a document's tree or to create a new fragment of a
document. Imagine implementing a user command like cut or rearranging a
document by moving fragments around. It is desirable to have an object
which can hold such fragments and it is quite natural to use a Node for
this purpose. While it is true that a <code>Document</code> object could
fulfill this role, a <code>Document</code> object can potentially be a
heavyweight object, depending on the underlying implementation. What is
really needed for this is a very lightweight object.
<code>DocumentFragment</code> is such an object.</p>
<p>Furthermore, various operations -- such as inserting nodes as children
of another <code>Node</code> -- may take <code>DocumentFragment</code>
objects as arguments; this results in all the child nodes of the
<code>DocumentFragment</code> being moved to the child list of this
node.</p>
<p>The children of a <code>DocumentFragment</code> node are zero or more
nodes representing the tops of any sub-trees defining the structure of
the document. <code>DocumentFragment</code> nodes do not need to be
<termref def="dt-well-formed">well-formed XML documents</termref> (although they do need to follow the rules
imposed upon well-formed XML parsed entities, which can have multiple top
nodes). For example, a <code>DocumentFragment</code> might have only one
child and that child node could be a <code>Text</code> node. Such a
structure model represents neither an HTML document nor a well-formed XML
document.</p>
<p>When a <code>DocumentFragment</code> is inserted into a
<code>Document</code> (or indeed any other <code>Node</code> that may
take children) the children of the <code>DocumentFragment</code> and not
the <code>DocumentFragment</code> itself are inserted into the
<code>Node</code>. This makes the <code>DocumentFragment</code> very
useful when the user wishes to create nodes that are <termref def="dt-sibling">siblings</termref>; the
<code>DocumentFragment</code> acts as the parent of these nodes so that
the user can use the standard methods from the <code>Node</code>
interface, such as <code>insertBefore</code> and
<code>appendChild</code>.</p>
</descr>
</interface>
<!--[ Document object description ]-->
<interface name="Document" inherits="Node" id="i-Document">
<descr><p>The <code>Document</code> interface represents the entire
HTML or XML document. Conceptually, it is the <termref def="dt-root-node">root</termref> of the
document tree, and provides the primary access to the
document's data.</p>
<p>Since elements, text nodes, comments, processing instructions,
etc. cannot exist outside the context of a <code>Document</code>, the
<code>Document</code> interface also contains the factory methods needed
to create these objects. The <code>Node</code> objects created have a
<code>ownerDocument</code> attribute which associates them with the
<code>Document</code> within whose context they were created.</p>
</descr>
<attribute readonly="yes" name="doctype" type="DocumentType"
id="ID-B63ED1A31">
<descr><p>The Document Type Declaration (see <code>DocumentType</code>)
associated with this document. For HTML documents as well as XML
documents without a document type declaration this returns
<code>null</code>. The DOM Level 2 does not support editing the
Document Type Declaration. <code>docType</code> cannot be
altered in any way, including through the use of methods inherited from
the <code>Node</code> interface, such as <code>insertNode</code> or
<code>removeNode</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" name="implementation" type="DOMImplementation"
id="ID-1B793EBA">
<descr><p>The <code>DOMImplementation</code> object that handles this
document. A DOM application may use objects from multiple
implementations.</p>
</descr>
</attribute>
<attribute readonly="yes" name="documentElement" type="Element"
id="ID-87CD092">
<descr><p>This is a <termref def="dt-convenience">convenience</termref> attribute that allows direct
access to the child node that is the root element of the
document. For HTML documents, this is the element with
the tagName "HTML".</p></descr>
</attribute>
<!-- ********** -->
<method name="createElement" id="ID-2141741547">
<descr><p>Creates an element of the type specified. Note that the instance
returned implements the <code>Element</code> interface, so attributes
can be specified directly on the returned object.</p>
<p>In addition, if there are known attributes with default values,
<code>Attr</code> nodes representing them are automatically created and
attached to the element.</p>
<p>To create an element with a qualified name and namespace URI, use the
<code>createElementNS</code> method.</p>
</descr>
<parameters>
<param name="tagName" type="DOMString" attr="in">
<descr><p>The name of the element type to
instantiate. For XML, this is case-sensitive. For HTML, the
<code>tagName</code> parameter may be provided in any case,
but it must be mapped to the canonical uppercase form by
the DOM implementation.
</p></descr>
</param>
</parameters>
<returns type="Element">
<descr><p>A new <code>Element</code> object with the
<code>nodeName</code> attribute set to <code>tagName</code>, and
<code>localName</code>, <code>prefix</code>, and
<code>namespaceURI</code> set to <code>null</code>.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
an illegal character.</p></descr>
</exception>
</raises>
</method>
<!-- ********** -->
<method name="createDocumentFragment" id="ID-35CB04B5">
<descr><p>Creates an empty <code>DocumentFragment</code> object.
</p></descr>
<parameters>
<!-- No parameters -->
</parameters>
<returns type="DocumentFragment">
<descr><p>A new <code>DocumentFragment</code>.</p></descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<!-- ********** -->
<method name="createTextNode" id="ID-1975348127">
<descr><p>Creates a <code>Text</code> node given the specified
string.</p></descr>
<parameters>
<param name="data" type="DOMString" attr="in">
<descr><p>The data for the node.</p></descr>
</param>
</parameters>
<returns type="Text">
<descr><p>The new <code>Text</code> object.</p></descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<!-- ********** -->
<method name="createComment" id="ID-1334481328">
<descr><p>Creates a <code>Comment</code> node given the specified
string.</p></descr>
<parameters>
<param name="data" type="DOMString" attr="in">
<descr><p>The data for the node.</p></descr>
</param>
</parameters>
<returns type="Comment">
<descr><p>The new <code>Comment</code> object.</p></descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<!-- ********** -->
<method name="createCDATASection" id="ID-D26C0AF8">
<descr><p>Creates a <code>CDATASection</code> node whose value is
the specified string.</p></descr>
<parameters>
<param name="data" type="DOMString" attr="in">
<descr><p>The data for the <code>CDATASection</code> contents.</p>
</descr>
</param>
</parameters>
<returns type="CDATASection">
<descr><p>The new <code>CDATASection</code> object.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NOT_SUPPORTED_ERR: Raised if this document is an HTML
document.</p></descr>
</exception>
</raises>
</method>
<!-- ********** -->
<method name="createProcessingInstruction" id="ID-135944439">
<descr><p>Creates a <code>ProcessingInstruction</code> node given
the specified name and data strings.</p></descr>
<parameters>
<param name="target" type="DOMString" attr="in">
<descr><p>The target part of the processing instruction.</p></descr>
</param>
<param name="data" type="DOMString" attr="in">
<descr><p>The data for the node.</p></descr>
</param>
</parameters>
<returns type="ProcessingInstruction">
<descr><p>The new <code>ProcessingInstruction</code> object.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified target
contains an illegal character.</p>
<p>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.</p>
</descr>
</exception>
</raises>
</method>
<!-- ********** -->
<method name="createAttribute" id="ID-1084891198">
<descr><p>Creates an <code>Attr</code> of the given name.
Note that the <code>Attr</code> instance
can then be set on an <code>Element</code> using the
<code>setAttributeNode</code> method. </p>
<p>To create an attribute with a qualified name and namespace URI, use
the <code>createAttributeNS</code> method.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute.</p></descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>A new <code>Attr</code> object with the <code>nodeName</code>
attribute set to <code>name</code>, and <code>localName</code>,
<code>prefix</code>, and <code>namespaceURI</code> set to
<code>null</code>. The value of the attribute is the empty
string.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
an illegal character.</p></descr>
</exception>
</raises>
</method>
<method name="createEntityReference" id="ID-392B75AE">
<descr><p>Creates an <code>EntityReference</code> object. In addition, if
the referenced entity is known, the child list of the
<code>EntityReference</code> node is made the same as that of the
corresponding <code>Entity</code> node.</p>
<note><p>If any descendant of the <code>Entity</code> node has an
unbound <termref def='dt-namespaceprefix'>namespace prefix</termref>,
the corresponding descendant of the created
<code>EntityReference</code> node is also unbound; (its
<code>namespaceURI</code> is <code>null</code>). The DOM Level 2 does
not support any mechanism to resolve namespace prefixes.</p></note>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the entity to reference. </p>
</descr>
</param>
</parameters>
<returns type="EntityReference">
<descr><p>The new <code>EntityReference</code> object.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
an illegal character.</p>
<p>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.</p>
</descr>
</exception>
</raises>
</method>
<!-- ********** -->
<method name="getElementsByTagName" id="ID-A6C9094">
<descr><p>Returns a <code>NodeList</code> of all the <code>Elements</code>
with a given tag name in the order in which they are encountered
in a preorder traversal of the <code>Document</code> tree.
</p></descr>
<parameters>
<param name="tagname" type="DOMString" attr="in">
<descr><p>The name of the tag to match on. The special value "*"
matches all tags.</p></descr>
</param>
</parameters>
<returns type="NodeList">
<descr><p>A new <code>NodeList</code> object containing
all the matched <code>Elements</code>.</p></descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<!-- ****** DOM Level 2 additions ****** -->
<method name="importNode" id="Core-Document-importNode" since="DOM Level 2">
<descr>
<p>Imports a node from another document to this document. The returned
node has no parent; (<code>parentNode</code> is <code>null</code>). The
source node is not altered or removed from the original document; this
method creates a new copy of the source node.</p>
<p>For all nodes, importing a node creates a node object owned by the
importing document, with attribute values identical to the source
node's <code>nodeName</code> and <code>nodeType</code>, plus the
attributes related to namespaces (<code>prefix</code>,
<code>localName</code>, and <code>namespaceURI</code>). As in the
<code>cloneNode</code> operation on a <code>Node</code>, the source
node is not altered.</p>
<p>Additional information is copied as appropriate to the
<code>nodeType</code>, attempting to mirror the behavior expected if a
fragment of XML or HTML source was copied from one document to another,
recognizing that the two documents may have different DTDs in the XML
case. The following list describes the specifics for each type of
node.
<glist>
<gitem>
<label>ATTRIBUTE_NODE</label>
<def><p>The <code>ownerElement</code> attribute is set to
<code>null</code> and the <code>specified</code> flag is set to
<code>true</code> on the generated <code>Attr</code>. The
<termref def="dt-descendant">descendants</termref> of the source <code>Attr</code> are recursively
imported and the resulting nodes reassembled to form the
corresponding subtree.</p>
<p>Note that the <code>deep</code> parameter has no effect on
<code>Attr</code> nodes; they always carry their children with
them when imported.</p>
</def>
</gitem>
<gitem>
<label>DOCUMENT_FRAGMENT_NODE</label>
<def><p>If the <code>deep</code> option was set to
<code>true</code>, the <termref def="dt-descendant">descendants</termref> of the source element are
recursively imported and the resulting nodes reassembled to
form the corresponding subtree. Otherwise, this simply
generates an empty <code>DocumentFragment</code>.</p>
</def>
</gitem>
<gitem>
<label>DOCUMENT_NODE</label>
<def><p><code>Document</code> nodes cannot be imported.</p>
</def>
</gitem>
<gitem>
<label>DOCUMENT_TYPE_NODE</label>
<def><p><code>DocumentType</code> nodes cannot be imported.</p>
</def>
</gitem>
<gitem>
<label>ELEMENT_NODE</label>
<def><p><emph>Specified</emph> attribute nodes of the source
element are imported, and the generated <code>Attr</code> nodes
are attached to the generated <code>Element</code>. Default
attributes are <emph>not</emph> copied, though if the document
being imported into defines default attributes for this element
name, those are assigned. If the <code>importNode</code>
<code>deep</code> parameter was set to <code>true</code>, the
<termref def="dt-descendant">descendants</termref> of the source element are recursively imported
and the resulting nodes reassembled to form the corresponding
subtree.</p>
</def>
</gitem>
<gitem>
<label>ENTITY_NODE</label>
<def><p><code>Entity</code> nodes can be imported, however in the
current release of the DOM the <code>DocumentType</code> is
readonly. Ability to add these imported nodes to a
<code>DocumentType</code> will be considered for addition to a
future release of the DOM.</p>
<p>On import, the <code>publicId</code>, <code>systemId</code>,
and <code>notationName</code> attributes are copied. If a
<code>deep</code> import is requested, the <termref def="dt-descendant">descendants</termref> of the
the source <code>Entity</code> are recursively imported and the
resulting nodes reassembled to form the corresponding
subtree.</p>
</def>
</gitem>
<gitem>
<label>ENTITY_REFERENCE_NODE</label>
<def><p>Only the <code>EntityReference</code> itself is copied,
even if a <code>deep</code> import is requested, since the
source and destination documents might have defined the entity
differently. If the document being imported into provides a
definition for this entity name, its value is assigned.</p>
</def>
</gitem>
<gitem>
<label>NOTATION_NODE</label>
<def><p><code>Notation</code> nodes can be imported, however in the
current release of the DOM the <code>DocumentType</code> is
readonly. Ability to add these imported nodes to a
<code>DocumentType</code> will be considered for addition to a
future release of the DOM.</p>
<p>On import, the <code>publicId</code> and
<code>systemId</code> attributes are copied.</p>
<p>Note that the <code>deep</code> parameter has no effect on
<code>Notation</code> nodes since they never have any
children.</p>
</def>
</gitem>
<gitem>
<label>PROCESSING_INSTRUCTION_NODE</label>
<def><p>The imported node copies its <code>target</code> and
<code>data</code> values from those of the source node.</p>
</def>
</gitem>
<gitem>
<label>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE</label>
<def><p>These three types of nodes inheriting from
<code>CharacterData</code> copy their <code>data</code> and
<code>length</code> attributes from those of the source
node.</p>
</def>
</gitem>
</glist>
</p>
</descr>
<parameters>
<param name="importedNode" type="Node" attr="in">
<descr><p>The node to import.</p></descr>
</param>
<param name="deep" type="boolean" attr="in">
<descr><p>If <code>true</code>, recursively import the subtree
under the specified node; if <code>false</code>, import only
the node itself, as explained above. This has no effect on
<code>Attr</code>, <code>EntityReference</code>, and
<code>Notation</code> nodes.</p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr><p>The imported node that belongs to this
<code>Document</code>.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NOT_SUPPORTED_ERR: Raised if the type of node being imported
is not supported.</p></descr>
</exception>
</raises>
</method>
<method name="createElementNS" id="ID-DocCrElNS" since="DOM Level 2">
<descr><p>Creates an element of the given qualified name and namespace
URI. HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the element to create.</p>
</descr>
</param>
<param name="qualifiedName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
of the element type to instantiate.</p>
</descr>
</param>
</parameters>
<returns type="Element">
<descr><p>A new <code>Element</code> object with the following
attributes:</p>
<table summary='Layout table: the first cell the name property,
the second cell contains his initial value'>
<tbody>
<tr><th>Attribute</th><th>Value</th></tr>
<tr><td><code>Node.nodeName</code></td>
<td><code>qualifiedName</code></td>
</tr>
<tr><td><code>Node.namespaceURI</code></td>
<td><code>namespaceURI</code></td></tr>
<tr><td><code>Node.prefix</code></td><td>prefix, extracted from
<code>qualifiedName</code>, or <code>null</code> if there is no
prefix</td></tr>
<tr><td><code>Node.localName</code></td><td><termref
def='dt-localname'>local name</termref>, extracted from
<code>qualifiedName</code></td></tr>
<tr><td><code>Element.tagName</code></td>
<td><code>qualifiedName</code></td>
</tr>
</tbody>
</table>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
contains an illegal character.</p>
<p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
malformed, if the <code>qualifiedName</code> has a prefix and
the <code>namespaceURI</code> is <code>null</code>, or if
the <code>qualifiedName</code> has a prefix that
is "xml" and the <code>namespaceURI</code> is different
from "<loc href='&xml-ns;'>&xml-ns;</loc>" <bibref
ref='Namespaces'/>.</p>
</descr>
</exception>
</raises>
</method>
<method name="createAttributeNS" id="ID-DocCrAttrNS" since="DOM Level 2">
<descr><p>Creates an attribute of the given qualified name and namespace
URI. HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to create.</p>
</descr>
</param>
<param name="qualifiedName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
of the attribute to instantiate.</p>
</descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>A new <code>Attr</code> object with the following
attributes:</p>
<table summary='Layout table: the first cell the name property,
the second cell contains his initial value'>
<tbody>
<tr><th>Attribute</th><th>Value</th></tr>
<tr><td><code>Node.nodeName</code></td><td>qualifiedName</td>
</tr>
<tr><td><code>Node.namespaceURI</code></td>
<td><code>namespaceURI</code></td></tr>
<tr><td><code>Node.prefix</code></td><td>prefix, extracted from
<code>qualifiedName</code>, or <code>null</code> if there is no
prefix</td></tr>
<tr><td><code>Node.localName</code></td><td><termref
def='dt-localname'>local name</termref>, extracted from
<code>qualifiedName</code></td></tr>
<tr><td><code>Attr.name</code></td>
<td><code>qualifiedName</code></td></tr>
<tr><td><code>Node.nodeValue</code></td>
<td>the empty string</td></tr>
</tbody>
</table>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
contains an illegal character.</p>
<p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
malformed, if the <code>qualifiedName</code> has a prefix and
the <code>namespaceURI</code> is <code>null</code>, if the
<code>qualifiedName</code> has a prefix that is
"xml" and the <code>namespaceURI</code> is different from
"<loc href='&xml-ns;'>&xml-ns;</loc>", or if the
<code>qualifiedName</code> is "xmlns" and the
<code>namespaceURI</code> is different from
"<loc href='&xmlns-ns;'>&xmlns-ns;</loc>".</p>
</descr>
</exception>
</raises>
</method>
<method name="getElementsByTagNameNS" id="ID-getElBTNNS" since="DOM Level 2">
<descr><p>Returns a <code>NodeList</code> of all the <code>Elements</code>
with a given <termref def='dt-localname'>local name</termref> and
namespace URI in the order in which they are encountered in a
preorder traversal of the <code>Document</code> tree.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the elements to match on. The special value "*" matches all
namespaces.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
elements to match on. The special value "*" matches all local
names.</p>
</descr>
</param>
</parameters>
<returns type="NodeList">
<descr><p>A new <code>NodeList</code> object containing all the matched
<code>Elements</code>.</p></descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<method name="getElementById" id="ID-getElBId" since="DOM Level 2">
<descr><p>Returns the <code>Element</code> whose <code>ID</code>
is given by <code>elementId</code>. If no such element exists, returns
<code>null</code>. Behavior is not defined if more than one element has
this <code>ID</code>.
<note><p>The DOM implementation must have information that says which
attributes are of type ID. Attributes with the name "ID" are not of type ID unless
so defined. Implementations that do not know whether attributes are of type
ID or not are expected to return <code>null</code>.</p></note></p></descr>
<parameters>
<param name="elementId" type="DOMString" attr="in">
<descr><p>The unique <code>id</code> value for an element.</p></descr>
</param>
</parameters>
<returns type="Element">
<descr><p>The matching element.</p></descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
</interface>
+128
View File
@@ -0,0 +1,128 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ DOMImplementation object description ]-->
<!-- $Date$ $Revision$ -->
<interface name="DOMImplementation" id="ID-102161490">
<descr><p>The <code>DOMImplementation</code> interface provides a
number of methods for performing operations that are independent
of any particular instance of the document object model.</p>
</descr>
<method name="hasFeature" id="ID-5CED94D7">
<descr><p>Test if the DOM implementation implements a
specific feature.</p></descr>
<parameters>
<param name="feature" type="DOMString" attr="in">
<descr><p>The name of the feature to test (case-insensitive). The
values used by DOM features are defined throughout the DOM Level 2 specifications and listed in
the <specref ref="ID-Conformance"/> section. The name must be an
<termref def="dt-XML-name">XML name</termref>. To avoid possible
conflicts, as a convention, names referring to features defined
outside the DOM specification should be made unique by reversing the name of
the Internet domain name of the person (or the organization that the
person belongs to) who defines the feature, component by component,
and using this as a prefix. For instance, the W3C SVG Working Group
defines the feature "org.w3c.dom.svg".</p></descr>
</param>
<param name="version" type="DOMString" attr="in">
<descr><p>This is the version number of the feature to test. In Level
2, the string can be either "2.0" or "1.0". If the version is not
specified, supporting any version of the feature causes the method
to return <code>true</code>.</p></descr>
</param>
</parameters>
<returns type="boolean">
<descr><p><code>true</code> if the feature is implemented in the
specified version, <code>false</code> otherwise.</p></descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<!-- ****** DOM Level 2 additions ****** -->
<method name="createDocumentType" id="Level-2-Core-DOM-createDocType"
since="DOM Level 2">
<descr><p>Creates an empty <code>DocumentType</code> node. Entity
declarations and notations are not made available. Entity reference
expansions and default attribute additions do not occur. It is expected
that a future version of the DOM will provide a way for populating a
<code>DocumentType</code>.</p>
<p>HTML-only DOM implementations do not need to
implement this method.</p>
</descr>
<parameters>
<param name="qualifiedName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
of the document type to be created. </p>
</descr>
</param>
<param name="publicId" type="DOMString" attr="in">
<descr><p>The external subset public identifier.</p>
</descr>
</param>
<param name="systemId" type="DOMString" attr="in">
<descr><p>The external subset system identifier.</p>
</descr>
</param>
</parameters>
<returns type="DocumentType">
<descr><p>A new <code>DocumentType</code> node with
<code>Node.ownerDocument</code> set to <code>null</code>.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
contains an illegal character.</p>
<p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
malformed.</p>
</descr>
</exception>
</raises>
</method>
<method name="createDocument" id="Level-2-Core-DOM-createDocument"
since="DOM Level 2">
<descr><p>Creates an XML <code>Document</code> object of the specified type
with its document element. HTML-only DOM implementations do not need to
implement this method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the document element to create.</p>
</descr>
</param>
<param name="qualifiedName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
of the document element to be created.</p>
</descr>
</param>
<param name="doctype" type="DocumentType" attr="in">
<descr><p>The type of document to be created or <code>null</code>.</p>
<p>When <code>doctype</code> is not <code>null</code>, its
<code>Node.ownerDocument</code> attribute is set to the document
being created.</p>
</descr>
</param>
</parameters>
<returns type="Document">
<descr><p>A new <code>Document</code> object.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
contains an illegal character.</p>
<p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
malformed, if the <code>qualifiedName</code> has a prefix and
the <code>namespaceURI</code> is <code>null</code>, or if
the <code>qualifiedName</code> has a prefix that
is "xml" and the <code>namespaceURI</code> is different
from "<loc href='&xml-ns;'>&xml-ns;</loc>" <bibref
ref='Namespaces'/>.</p>
<p>WRONG_DOCUMENT_ERR: Raised if <code>doctype</code> has already
been used with a different document or was created from a different
implementation.</p>
</descr>
</exception>
</raises>
</method>
</interface>
+462
View File
@@ -0,0 +1,462 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date$ $Revision$ -->
<!--[ Element object description ]-->
<interface name="Element" inherits="Node" id="ID-745549614">
<descr><p>The <code>Element</code> interface represents an <termref def="dt-element">element</termref> in an HTML
or XML document. Elements may have attributes associated with them; since the
<code>Element</code> interface inherits from <code>Node</code>, the generic
<code>Node</code> interface attribute <code>attributes</code> may be used
to retrieve the set of all attributes for an element. There are methods on
the <code>Element</code> interface to retrieve either an <code>Attr</code>
object by name or an attribute value by name. In XML, where an attribute
value may contain entity references, an <code>Attr</code> object should be
retrieved to examine the possibly fairly complex sub-tree representing the
attribute value. On the other hand, in HTML, where all attributes have
simple string values, methods to directly access an attribute value can
safely be used as a <termref def="dt-convenience">convenience</termref>.</p>
<note><p>In DOM Level 2, the method <code>normalize</code> is
inherited from the <code>Node</code> interface where it was
moved.</p></note>
</descr>
<attribute type="DOMString" name="tagName" readonly="yes" id="ID-104682815">
<descr><p>The name of the element. For example, in:
<eg role="code">
&lt;elementExample id="demo"&gt;
...
&lt;/elementExample&gt; ,
</eg>
<code>tagName</code> has the value
<code>"elementExample"</code>. Note that this is
case-preserving in XML, as are all of the operations of the DOM.
The HTML DOM returns the <code>tagName</code> of an HTML element
in the canonical uppercase form, regardless of the case in the
source HTML document. </p>
</descr>
</attribute>
<method name="getAttribute" id="ID-666EE0F9">
<descr><p>Retrieves an attribute value by name.</p></descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to retrieve.</p></descr>
</param>
</parameters>
<returns type="DOMString">
<descr><p>The <code>Attr</code> value as a string, or the empty string if
that attribute does not have a specified or default value.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttribute" id="ID-F68F082">
<descr><p>Adds a new attribute. If an attribute with that name is already
present in the element, its value is changed to be that of the value
parameter. This value is a simple string; it is not parsed as it is being
set. So any markup (such as syntax to be recognized as an entity
reference) is treated as literal text, and needs to be appropriately
escaped by the implementation when it is written out. In order to assign
an attribute value that contains entity references, the user must create
an <code>Attr</code> node plus any <code>Text</code> and
<code>EntityReference</code> nodes, build the appropriate subtree, and
use <code>setAttributeNode</code> to assign it as the value of an
attribute.</p>
<p>To set an attribute with a qualified name and namespace URI, use
the <code>setAttributeNS</code> method.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to create or alter.</p></descr>
</param>
<param name="value" type="DOMString" attr="in">
<descr><p>Value to set in string form.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
an illegal character.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="removeAttribute" id="ID-6D6AC0F9">
<descr><p>Removes an attribute by name. If the removed attribute is known
to have a default value, an attribute immediately appears containing
the default value as well as the corresponding namespace URI,
local name, and prefix when applicable.</p>
<p>To remove an attribute by local name and namespace URI, use
the <code>removeAttributeNS</code> method.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to remove.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="getAttributeNode" id="ID-217A91B8">
<descr><p>Retrieves an attribute node by name.</p>
<p>To retrieve an attribute node by qualified name and namespace URI, use
the <code>getAttributeNodeNS</code> method.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name (<code>nodeName</code>) of the attribute to
retrieve.</p></descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>The <code>Attr</code> node with the specified
name (<code>nodeName</code>) or <code>null</code> if there is no such
attribute.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttributeNode" id="ID-887236154">
<descr><p>Adds a new attribute node. If an attribute with that name
(<code>nodeName</code>) is already present in the element, it is replaced
by the new one.</p>
<p>To add a new attribute node with a qualified name and namespace URI,
use the <code>setAttributeNodeNS</code> method.</p>
</descr>
<parameters>
<param name="newAttr" type="Attr" attr="in">
<descr><p>The <code>Attr</code> node to add to the attribute
list.</p></descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>If the <code>newAttr</code> attribute replaces
an existing attribute, the replaced <code>Attr</code> node is
returned, otherwise <code>null</code> is returned.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was
created from a different document than the one that created the
element.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already
an attribute of another <code>Element</code> object. The
DOM user must explicitly clone <code>Attr</code>
nodes to re-use them in other elements.</p></descr>
</exception>
</raises>
</method>
<method name="removeAttributeNode" id="ID-D589198">
<descr><p>Removes the specified attribute node. If the removed
<code>Attr</code> has a default value it is immediately
replaced. The replacing attribute has the same namespace URI
and local name, as well as the original prefix, when
applicable.</p>
</descr>
<parameters>
<param name="oldAttr" type="Attr" attr="in">
<descr><p>The <code>Attr</code> node to remove from the attribute
list.</p></descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>The <code>Attr</code> node that was removed.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
readonly.</p>
<p>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute of
the element.</p>
</descr>
</exception>
</raises>
</method>
<method name="getElementsByTagName" id="ID-1938918D">
<descr><p>Returns a <code>NodeList</code> of all <termref def="dt-descendant">descendant</termref>
<code>Elements</code> with a given tag name, in the order in which they
are encountered in a preorder traversal of this <code>Element</code>
tree.</p></descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the tag to match on. The special value "*"
matches all tags.</p></descr>
</param>
</parameters>
<returns type="NodeList">
<descr><p>A list of matching <code>Element</code> nodes.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<!-- ****** DOM Level 2 additions ****** -->
<method name="getAttributeNS" id="ID-ElGetAttrNS" since="DOM Level 2">
<descr><p>Retrieves an attribute value by local name and namespace
URI. HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to retrieve.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to retrieve.</p>
</descr>
</param>
</parameters>
<returns type="DOMString">
<descr><p>The <code>Attr</code> value as a string, or the empty string if
that attribute does not have a specified or default value.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttributeNS" id="ID-ElSetAttrNS" since="DOM Level 2">
<descr><p>Adds a new attribute. If an attribute with the same local name
and namespace URI is already present on the element, its prefix is
changed to be the prefix part of the <code>qualifiedName</code>, and
its value is changed to be the <code>value</code> parameter. This value
is a simple string; it is not parsed as it is being set. So any markup
(such as syntax to be recognized as an entity reference) is treated as
literal text, and needs to be appropriately escaped by the
implementation when it is written out. In order to assign an attribute
value that contains entity references, the user must create an
<code>Attr</code> node plus any <code>Text</code> and
<code>EntityReference</code> nodes, build the appropriate subtree, and
use <code>setAttributeNodeNS</code> or <code>setAttributeNode</code> to
assign it as the value of an attribute.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to create or alter.</p>
</descr>
</param>
<param name="qualifiedName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
of the attribute to create or alter.</p>
</descr>
</param>
<param name="value" type="DOMString" attr="in">
<descr><p>The value to set in string form.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
contains an illegal character.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
malformed, if the <code>qualifiedName</code> has a prefix and
the <code>namespaceURI</code> is <code>null</code>, if the
<code>qualifiedName</code> has a prefix that is
"xml" and the <code>namespaceURI</code> is different from
"<loc href='&xml-ns;'>&xml-ns;</loc>", or if the
<code>qualifiedName</code> is "xmlns" and the
<code>namespaceURI</code> is different from
"<loc href='&xmlns-ns;'>&xmlns-ns;</loc>".</p>
</descr>
</exception>
</raises>
</method>
<method name="removeAttributeNS" id="ID-ElRemAtNS" since="DOM Level 2">
<descr><p>Removes an attribute by local name and namespace URI. If
the removed attribute has a default value it is immediately
replaced. The replacing attribute has the same namespace URI
and local name, as well as the original prefix.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to remove.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to remove.</p>
</descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="getAttributeNodeNS" id="ID-ElGetAtNodeNS" since="DOM Level 2">
<descr><p>Retrieves an <code>Attr</code> node by local name and namespace
URI. HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to retrieve.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to retrieve.</p>
</descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>The <code>Attr</code> node with the specified attribute local
name and namespace URI or <code>null</code> if there is no such
attribute.</p>
</descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttributeNodeNS" id="ID-ElSetAtNodeNS" since="DOM Level 2">
<descr><p>Adds a new attribute. If an attribute with that local name and
that namespace URI is already present in the element, it is replaced by
the new one.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="newAttr" type="Attr" attr="in">
<descr><p>The <code>Attr</code> node to add to the attribute list.</p>
</descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>If the <code>newAttr</code> attribute replaces an existing
attribute with the same <termref def='dt-localname'>local
name</termref> and <termref def='dt-namespaceURI'>namespace
URI</termref>, the replaced <code>Attr</code> node is
returned, otherwise <code>null</code> is returned.</p>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was
created from a different document than the one that created the
element.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
attribute of another <code>Element</code> object. The DOM user
must explicitly clone <code>Attr</code> nodes to re-use them in
other elements.</p>
</descr>
</exception>
</raises>
</method>
<method name="getElementsByTagNameNS" id="ID-A6C90942" since="DOM Level 2">
<descr><p>Returns a <code>NodeList</code> of all the <termref def="dt-descendant">descendant</termref>
<code>Elements</code> with a given local name and namespace URI in the
order in which they are encountered in a preorder traversal of this
<code>Element</code> tree.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the elements to match on. The special value "*" matches all
namespaces.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
elements to match on. The special value "*" matches all local
names.</p>
</descr>
</param>
</parameters>
<returns type="NodeList">
<descr><p>A new <code>NodeList</code> object containing all the matched
<code>Elements</code>.</p>
</descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<method name="hasAttribute" id="ID-ElHasAttr" since="DOM Level 2">
<descr><p>Returns <code>true</code> when an attribute with a given name is
specified on this element or has a default value, <code>false</code>
otherwise.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to look for.</p></descr>
</param>
</parameters>
<returns type="boolean">
<descr><p><code>true</code> if an attribute with the given name is
specified on this element or has a default value, <code>false</code>
otherwise.</p>
</descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="hasAttributeNS" id="ID-ElHasAttrNS" since="DOM Level 2">
<descr><p>Returns <code>true</code> when an attribute with a given local
name and namespace URI is specified on this element or has a default
value, <code>false</code> otherwise. HTML-only DOM implementations do
not need to implement this method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to look for.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to look for.</p>
</descr>
</param>
</parameters>
<returns type="boolean">
<descr><p><code>true</code> if an attribute with the given local name and
namespace URI is specified or has a default value on this element,
<code>false</code> otherwise.</p>
</descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
</interface>
@@ -0,0 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
<interface name="EntityReference" inherits="Node" id="ID-11C98490">
<descr><p><code>EntityReference</code> objects may be inserted into the
structure model when an entity reference is in the source document, or
when the user wishes to insert an entity reference. Note that character
references and references to predefined entities are considered to be
expanded by the HTML or XML processor so that characters are represented
by their Unicode equivalent rather than by an entity reference. Moreover,
the XML processor may completely expand references to entities while
building the structure model, instead of providing
<code>EntityReference</code> objects. If it does provide such objects,
then for a given <code>EntityReference</code> node, it may be that there
is no <code>Entity</code> node representing the referenced entity. If
such an <code>Entity</code> exists, then the subtree of the
<code>EntityReference</code> node is in general a copy of the
<code>Entity</code> node subtree. However, this may not be true when an
entity contains an unbound <termref def='dt-namespaceprefix'>namespace
prefix</termref>. In such a case, because the namespace prefix resolution
depends on where the entity reference is, the <termref def="dt-descendant">descendants</termref> of the
<code>EntityReference</code> node may be bound to different
<termref def='dt-namespaceURI'>namespace URIs</termref>.</p>
<p>As for <code>Entity</code> nodes, <code>EntityReference</code> nodes and
all their <termref def="dt-descendant">descendants</termref> are
<termref def="dt-readonly-node">readonly</termref>.</p>
</descr>
</interface>
+57
View File
@@ -0,0 +1,57 @@
<?xml version="1.0" encoding="UTF-8"?>
<interface name="Entity" inherits="Node" id="ID-527DCFF2">
<descr><p>This interface represents an entity, either parsed or
unparsed, in an XML document. Note that this models the entity
itself <emph>not</emph> the entity declaration. <code>Entity</code>
declaration modeling has been left for a later Level of the DOM
specification.</p>
<p>The <code>nodeName</code> attribute that is inherited from
<code>Node</code> contains the name of the entity.</p>
<p>An XML processor may choose to completely expand entities before
the structure model is passed to the DOM; in this case there will
be no <code>EntityReference</code> nodes in the document tree.</p>
<p>XML does not mandate that a non-validating XML processor read
and process entity declarations made in the external subset or
declared in external parameter entities. This means
that parsed entities declared in the external subset
need not be expanded by some classes of applications, and that
the replacement value of the entity may not be available. When the
replacement value is available, the corresponding
<code>Entity</code> node's child list represents the structure of
that replacement text. Otherwise, the child list is empty.</p>
<p>The DOM Level 2 does not support editing <code>Entity</code>
nodes; if a user wants to make changes to the contents of an
<code>Entity</code>, every related <code>EntityReference</code> node
has to be replaced in the structure model by a clone of the
<code>Entity</code>'s contents, and then the desired changes must be made
to each of those clones instead. <code>Entity</code> nodes and all their
<termref def="dt-descendant">descendants</termref> are <termref def="dt-readonly-node">readonly</termref>.</p>
<p>An <code>Entity</code> node does not have any parent.</p>
<note><p>If the entity contains an unbound <termref
def='dt-namespaceprefix'>namespace prefix</termref>, the
<code>namespaceURI</code> of the corresponding node in the
<code>Entity</code> node subtree is <code>null</code>. The same is
true for <code>EntityReference</code> nodes that refer to this entity,
when they are created using the <code>createEntityReference</code>
method of the <code>Document</code> interface. The DOM Level 2 does not
support any mechanism to resolve namespace prefixes.</p></note>
</descr>
<attribute readonly="yes" name="publicId" type="DOMString" id="ID-D7303025">
<descr><p>The public identifier associated with the entity, if
specified. If the public identifier was not specified, this
is <code>null</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" name="systemId" type="DOMString" id="ID-D7C29F3E">
<descr><p>The system identifier associated with the entity, if
specified. If the system identifier was not specified, this
is <code>null</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" name="notationName" type="DOMString" id="ID-6ABAEB38">
<descr><p>For unparsed entities, the name of the notation for the
entity. For parsed entities, this is <code>null</code>. </p>
</descr>
</attribute>
</interface>
@@ -0,0 +1,90 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date$ $Revision$ -->
<!--[ Exceptions description ]-->
<exception name="DOMException" id="ID-17189187">
<descr>
<p>DOM operations only raise exceptions in &quot;exceptional&quot;
circumstances, i.e., when an operation is impossible
to perform (either for logical reasons, because data is lost, or
because the implementation has become unstable). In general, DOM methods
return specific error values in ordinary
processing situations, such as out-of-bound errors when using
<code>NodeList</code>.
</p>
<p>Implementations should raise other exceptions under other circumstances.
For example, implementations should raise an implementation-dependent
exception if a <code>null</code> argument is passed. </p>
<p>Some languages and object systems do not support the concept of
exceptions. For such systems, error conditions may be indicated using
native error reporting mechanisms. For some bindings, for example, methods
may return error codes similar to those listed in the corresponding method
descriptions.</p>
</descr>
<component id="ID-146F692A" name="code">
<typename>unsigned short</typename>
</component>
</exception>
<group id="ID-258A00AF" name="ExceptionCode">
<descr><p>An integer indicating the type of error generated.</p>
<note><p>Other numeric codes are reserved for W3C for possible future
use.</p></note>
</descr>
<constant name="INDEX_SIZE_ERR" type="unsigned short" value="1">
<descr><p>If index or size is negative, or greater than the
allowed value</p></descr>
</constant>
<constant name="DOMSTRING_SIZE_ERR" type="unsigned short" value="2">
<descr><p>If the specified range of text does not fit into a
DOMString</p></descr>
</constant>
<constant name="HIERARCHY_REQUEST_ERR" type="unsigned short" value="3">
<descr><p>If any node is inserted somewhere it doesn't belong</p></descr>
</constant>
<constant name="WRONG_DOCUMENT_ERR" type="unsigned short" value="4">
<descr><p>If a node is used in a different document than the one that
created it (that doesn't support it)</p></descr>
</constant>
<constant name="INVALID_CHARACTER_ERR" type="unsigned short" value="5">
<descr><p>If an invalid or illegal character is specified, such as in a
name. See <xspecref href="&xml-spec;#NT-Char">production 2</xspecref>
in the XML specification for the definition of a legal character, and
<xspecref href="&xml-spec;#NT-Name">production 5</xspecref>
for the definition of a legal name character.</p></descr></constant>
<constant name="NO_DATA_ALLOWED_ERR" type="unsigned short" value="6">
<descr><p>If data is specified for a node which does not support
data</p></descr></constant>
<constant name="NO_MODIFICATION_ALLOWED_ERR" type="unsigned short" value="7">
<descr><p>If an attempt is made to modify an object where modifications are
not allowed</p></descr></constant>
<constant name="NOT_FOUND_ERR" type="unsigned short" value="8">
<descr><p>If an attempt is made to reference a node in a context where it
does not exist</p></descr></constant>
<constant name="NOT_SUPPORTED_ERR" type="unsigned short" value="9">
<descr><p>If the implementation does not support the requested
type of object or operation.</p></descr></constant>
<constant name="INUSE_ATTRIBUTE_ERR" type="unsigned short" value="10">
<descr><p>If an attempt is made to add an attribute that is already in use
elsewhere</p></descr></constant>
<!-- ****** DOM Level 2 additions ****** -->
<constant name="INVALID_STATE_ERR" type="unsigned short" value="11"
since="DOM Level 2">
<descr><p>If an attempt is made to use an object that is not, or is no
longer, usable.</p></descr></constant>
<constant name="SYNTAX_ERR" type="unsigned short" value="12"
since="DOM Level 2">
<descr><p>If an invalid or illegal string is specified.</p></descr></constant>
<constant name="INVALID_MODIFICATION_ERR" type="unsigned short" value="13"
since="DOM Level 2">
<descr><p>If an attempt is made to modify the type of the underlying
object.</p></descr></constant>
<constant name="NAMESPACE_ERR" type="unsigned short" value="14"
since="DOM Level 2">
<descr><p>If an attempt is made to create or change an object in a way
which is incorrect with regard to namespaces.</p></descr>
</constant>
<constant name="INVALID_ACCESS_ERR" type="unsigned short" value="15"
since="DOM Level 2">
<descr><p>If a parameter or an operation is not supported by the
underlying object.</p></descr>
</constant>
</group>
@@ -0,0 +1,212 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date$ $Revision$ -->
<!--[ NamedNodeMap object description ]-->
<interface name="NamedNodeMap" id="ID-1780488922">
<descr><p>Objects implementing the <code>NamedNodeMap</code> interface are
used to represent collections of nodes that can be accessed by name. Note
that <code>NamedNodeMap</code> does not inherit from
<code>NodeList</code>; <code>NamedNodeMaps</code> are not maintained in
any particular order. Objects contained in an object implementing
<code>NamedNodeMap</code> may also be accessed by an ordinal index, but
this is simply to allow convenient enumeration of the contents of a
<code>NamedNodeMap</code>, and does not imply that the DOM specifies an
order to these Nodes. </p>
<p><code>NamedNodeMap</code> objects in the DOM are <termref
def="td-live">live</termref>.</p>
</descr>
<method name="getNamedItem" id="ID-1074577549">
<descr><p>Retrieves a node specified by name.</p></descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The <code>nodeName</code> of a node to retrieve.</p></descr>
</param>
</parameters>
<returns type="Node">
<descr><p>A <code>Node</code> (of any type) with the specified
<code>nodeName</code>, or <code>null</code> if it does not
identify any node in this map.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setNamedItem" id="ID-1025163788">
<descr>
<p>Adds a node using its <code>nodeName</code> attribute. If a node with
that name is already present in this map, it is replaced by the new
one.</p>
<p>As the <code>nodeName</code> attribute is used to
derive the name which the node must be stored under, multiple
nodes of certain types (those that have a "special" string
value) cannot be stored as the names would clash. This is seen
as preferable to allowing nodes to be aliased.</p>
</descr>
<parameters>
<param name="arg" type="Node" attr="in">
<descr><p>A node to store in this map. The node will later be
accessible using the value of its <code>nodeName</code>
attribute.</p></descr>
</param>
</parameters>
<returns type="Node">
<descr><p>If the new <code>Node</code> replaces an existing node the
replaced <code>Node</code> is returned, otherwise <code>null</code> is
returned.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created
from a different document than the one that created this map.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.</p>
<p>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an
<code>Attr</code> that is already an attribute of another
<code>Element</code> object. The DOM user must explicitly clone
<code>Attr</code> nodes to re-use them in other elements.</p></descr>
</exception>
</raises>
</method>
<method name="removeNamedItem" id="ID-D58B193">
<descr><p>Removes a node specified by name. When this map contains the
attributes attached to an element, if the removed attribute is
known to have a default value, an attribute immediately appears
containing the default value as well as the corresponding namespace
URI, local name, and prefix when applicable.</p></descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The <code>nodeName</code> of the node to remove.</p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr><p>The node removed from this map if a node with such a name
exists.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NOT_FOUND_ERR: Raised if there is no node named
<code>name</code> in this map.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="item" id="ID-349467F9">
<descr><p>Returns the <code>index</code>th item in the map.
If <code>index</code> is greater than or equal to the number
of nodes in this map, this returns <code>null</code>.</p>
</descr>
<parameters>
<param name="index" type="unsigned long" attr="in">
<descr><p>Index into this map.</p></descr>
</param>
</parameters>
<returns type="Node">
<descr><p>The node at the <code>index</code>th position in the map, or
<code>null</code> if that is not a valid index.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<attribute type="unsigned long" readonly = "yes" name="length"
id="ID-6D0FB19E">
<descr><p>The number of nodes in this map. The range of valid child node
indices is <code>0</code> to <code>length-1</code>
inclusive. </p></descr>
</attribute>
<method name="getNamedItemNS" id="ID-getNamedItemNS" since="DOM Level 2">
<descr><p>Retrieves a node specified by local name and namespace
URI. HTML-only DOM implementations do not need to implement this
method.</p></descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the node to retrieve.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
node to retrieve.</p></descr>
</param>
</parameters>
<returns type="Node">
<descr><p>A <code>Node</code> (of any type) with the specified
local name and namespace URI, or <code>null</code> if they do not
identify any node in this map.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setNamedItemNS" id="ID-setNamedItemNS" since="DOM Level 2">
<descr>
<p>Adds a node using its <code>namespaceURI</code> and
<code>localName</code>. If a node with that namespace URI and that
local name is already present in this map, it is replaced by the new
one.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="arg" type="Node" attr="in">
<descr><p>A node to store in this map. The node will later be
accessible using the value of its <code>namespaceURI</code> and
<code>localName</code> attributes.</p></descr>
</param>
</parameters>
<returns type="Node">
<descr><p>If the new <code>Node</code> replaces an existing node the
replaced <code>Node</code> is returned, otherwise <code>null</code>
is returned.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created
from a different document than the one that created this map.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.</p>
<p>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an
<code>Attr</code> that is already an attribute of another
<code>Element</code> object. The DOM user must explicitly clone
<code>Attr</code> nodes to re-use them in other elements.</p></descr>
</exception>
</raises>
</method>
<method name="removeNamedItemNS" id="ID-removeNamedItemNS"
since="DOM Level 2">
<descr><p>Removes a node specified by local name and namespace URI. A
removed attribute may be known to have a default value when this map
contains the attributes attached to an element, as returned by the
attributes attribute of the <code>Node</code> interface. If so, an
attribute immediately appears containing the default value as well as
the corresponding namespace URI, local name, and prefix when
applicable.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p></descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the node to remove.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
node to remove.</p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr><p>The node removed from this map if a node with such a local
name and namespace URI exists.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NOT_FOUND_ERR: Raised if there is no node with the specified
<code>namespaceURI</code> and <code>localName</code> in this
map.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.</p>
</descr>
</exception>
</raises>
</method>
</interface>
@@ -0,0 +1,35 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date$ $Revision$ -->
<!--[ NodeList object description ]-->
<interface name="NodeList" id="ID-536297177">
<descr><p>The <code>NodeList</code> interface provides the abstraction of an
ordered collection of nodes, without defining or constraining how this
collection is implemented. <code>NodeList</code> objects in the DOM are
<termref def="td-live">live</termref>.</p>
<p>The items in the <code>NodeList</code> are accessible via an
integral index, starting from 0.</p>
</descr>
<method name="item" id="ID-844377136">
<descr><p>Returns the <code>index</code>th item in the collection.
If <code>index</code> is greater than or equal to the number
of nodes in the list, this returns <code>null</code>.</p></descr>
<parameters>
<param name="index" type="unsigned long" attr="in">
<descr><p>Index into the collection.</p></descr>
</param>
</parameters>
<returns type="Node">
<descr><p>The node at the <code>index</code>th position in the
<code>NodeList</code>, or <code>null</code> if that is not a
valid index.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<attribute type="unsigned long" readonly = "yes" name="length" id="ID-203510337">
<descr><p>The number of nodes in the list. The range of valid child node
indices is 0 to <code>length-1</code> inclusive. </p></descr>
</attribute>
</interface>
+548
View File
@@ -0,0 +1,548 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date$ $Revision$ -->
<!--[ Node object description ]-->
<interface name="Node" id="ID-1950641247">
<descr>
<p>The <code>Node</code> interface is the primary datatype for the entire Document Object Model.
It represents a single node in the document tree. While all objects
implementing the <code>Node</code> interface expose methods for dealing with children, not all objects
implementing the <code>Node</code> interface may have children. For example, <code>Text</code> nodes may not have children, and adding children to such nodes results
in a <code>DOMException</code> being raised.</p>
<p>The attributes <code>nodeName</code>, <code>nodeValue</code> and <code>attributes</code> are included as a mechanism to get at node information without casting
down to the specific derived interface. In cases where there is no obvious
mapping of these attributes for a specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an <code>Element</code> or <code>attributes</code> for a <code>Comment</code>), this returns <code>null</code>. Note that the specialized interfaces may contain additional and more
convenient mechanisms to get and set the relevant information.</p>
</descr>
<group id="ID-1841493061" name="NodeType">
<descr>
<p>An integer indicating which type of node this is.</p>
<note>
<p>Numeric codes up to 200 are reserved to W3C for possible future
use.</p>
</note>
</descr>
<constant name="ELEMENT_NODE" type="unsigned short" value="1">
<descr>
<p>The node is an <code>Element</code>.</p>
</descr>
</constant>
<constant name="ATTRIBUTE_NODE" type="unsigned short" value="2">
<descr>
<p>The node is an <code>Attr</code>.</p>
</descr>
</constant>
<constant name="TEXT_NODE" type="unsigned short" value="3">
<descr>
<p>The node is a <code>Text</code> node.</p>
</descr>
</constant>
<constant name="CDATA_SECTION_NODE" type="unsigned short" value="4">
<descr>
<p>The node is a <code>CDATASection</code>.</p>
</descr>
</constant>
<constant name="ENTITY_REFERENCE_NODE" type="unsigned short" value="5">
<descr>
<p>The node is an <code>EntityReference</code>.</p>
</descr>
</constant>
<constant name="ENTITY_NODE" type="unsigned short" value="6">
<descr>
<p>The node is an <code>Entity</code>.</p>
</descr>
</constant>
<constant name="PROCESSING_INSTRUCTION_NODE" type="unsigned short"
value="7">
<descr>
<p>The node is a <code>ProcessingInstruction</code>.</p>
</descr>
</constant>
<constant name="COMMENT_NODE" type="unsigned short" value="8">
<descr>
<p>The node is a <code>Comment</code>.</p>
</descr>
</constant>
<constant name="DOCUMENT_NODE" type="unsigned short" value="9">
<descr>
<p>The node is a <code>Document</code>.</p>
</descr>
</constant>
<constant name="DOCUMENT_TYPE_NODE" type="unsigned short" value="10">
<descr>
<p>The node is a <code>DocumentType</code>.</p>
</descr>
</constant>
<constant name="DOCUMENT_FRAGMENT_NODE" type="unsigned short" value="11">
<descr>
<p>The node is a <code>DocumentFragment</code>.</p>
</descr>
</constant>
<constant name="NOTATION_NODE" type="unsigned short" value="12">
<descr>
<p>The node is a <code>Notation</code>.</p>
</descr>
</constant>
</group>
<p>The values of <code>nodeName</code>, <code>nodeValue</code>, and <code>attributes</code> vary according to the node type as follows:
<table summary='Layout table:
the first cell contains the name of the interface,
the second contains the value of the nodeName attribute for this interface,
the third contains the value of the nodeValue attribute for this interface and
the fourth contains the value of the attributes attribute for this interface'
border="1">
<tbody>
<tr>
<th>Interface</th>
<th>nodeName</th>
<th>nodeValue</th>
<th>attributes</th>
</tr>
<tr>
<td>Attr</td>
<td>name of attribute</td>
<td>value of attribute</td>
<td>null</td>
</tr>
<tr>
<td>CDATASection</td>
<td>#cdata-section</td>
<td>content of the CDATA Section</td>
<td>null</td>
</tr>
<tr>
<td>Comment</td>
<td>#comment</td>
<td>content of the comment</td>
<td>null</td>
</tr>
<tr>
<td>Document</td>
<td>#document</td>
<td>null</td>
<td>null</td>
</tr>
<tr>
<td>DocumentFragment</td>
<td>#document-fragment</td>
<td>null</td>
<td>null</td>
</tr>
<tr>
<td>DocumentType</td>
<td>document type name</td>
<td>null</td>
<td>null</td>
</tr>
<tr>
<td>Element</td>
<td>tag name</td>
<td>null</td>
<td>NamedNodeMap</td>
</tr>
<tr>
<td>Entity</td>
<td>entity name</td>
<td>null</td>
<td>null</td>
</tr>
<tr>
<td>EntityReference</td>
<td>name of entity referenced</td>
<td>null</td>
<td>null</td>
</tr>
<tr>
<td>Notation</td>
<td>notation name</td>
<td>null</td>
<td>null</td>
</tr>
<tr>
<td>ProcessingInstruction</td>
<td>target</td>
<td>entire content excluding the target</td>
<td>null</td>
</tr>
<tr>
<td>Text</td>
<td>#text</td>
<td>content of the text node</td>
<td>null</td>
</tr>
</tbody>
</table> </p>
<attribute type="DOMString" readonly="yes" name="nodeName" id="ID-F68D095">
<descr>
<p>The name of this node, depending on its type; see the table above.
</p>
</descr>
</attribute>
<attribute type="DOMString" name="nodeValue" id="ID-F68D080">
<descr>
<p>The value of this node, depending on its type; see the table above.
When it is defined to be <code>null</code>, setting it has no effect.</p>
</descr>
<setraises>
<exception name="DOMException">
<descr>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.</p>
</descr>
</exception>
</setraises>
<getraises>
<exception name="DOMException">
<descr>
<p>DOMSTRING_SIZE_ERR: Raised when it would return more characters
than fit in a <code>DOMString</code> variable on the implementation platform.</p>
</descr>
</exception>
</getraises>
</attribute>
<attribute type="unsigned short" name="nodeType" readonly="yes"
id="ID-111237558">
<descr>
<p>A code representing the type of the underlying object, as defined
above.</p>
</descr>
</attribute>
<attribute type="Node" readonly="yes" name="parentNode" id="ID-1060184317">
<descr>
<p>The <termref def="dt-parent">parent</termref> of this node. All nodes,
except <code>Attr</code>, <code>Document</code>, <code>DocumentFragment</code>, <code>Entity</code>, and <code>Notation</code> may have a parent. However, if a node has just been created and not yet
added to the tree, or if it has been removed from the tree, this is <code>null</code>.</p>
</descr>
</attribute>
<attribute type="NodeList" readonly="yes" name="childNodes"
id="ID-1451460987">
<descr>
<p>A <code>NodeList</code> that contains all children of this node. If there are no children, this
is a <code>NodeList</code> containing no nodes.</p>
</descr>
</attribute>
<attribute readonly="yes" type="Node" name="firstChild" id="ID-169727388">
<descr>
<p>The first child of this node. If there is no such node, this returns <code>null</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" type="Node" name="lastChild" id="ID-61AD09FB">
<descr>
<p>The last child of this node. If there is no such node, this returns <code>null</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" type="Node" name="previousSibling"
id="ID-640FB3C8">
<descr>
<p>The node immediately preceding this node. If there is no such node,
this returns <code>null</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" type="Node" name="nextSibling" id="ID-6AC54C2F">
<descr>
<p>The node immediately following this node. If there is no such node,
this returns <code>null</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" type="NamedNodeMap" name="attributes"
id="ID-84CF096">
<descr>
<p>A <code>NamedNodeMap</code> containing the attributes of this node (if it is an <code>Element</code>) or <code>null</code> otherwise. </p>
</descr>
</attribute>
<attribute readonly="yes" type="Document" name="ownerDocument"
id="node-ownerDoc" version="DOM Level 2">
<descr>
<p>The <code>Document</code> object associated with this node. This is also the <code>Document</code> object used to create new nodes. When this node is a <code>Document</code> or a <code>DocumentType</code> which is not used with any <code>Document</code> yet, this is <code>null</code>.</p>
</descr>
</attribute>
<method name="insertBefore" id="ID-952280727">
<descr>
<p>Inserts the node <code>newChild</code> before the existing child node <code>refChild</code>. If <code>refChild</code> is <code>null</code>, insert <code>newChild</code> at the end of the list of children.</p>
<p>If <code>newChild</code> is a <code>DocumentFragment</code> object, all of its children are inserted, in the same order, before <code>refChild</code>. If the <code>newChild</code> is already in the tree, it is first removed.</p>
</descr>
<parameters>
<param name="newChild" type="Node" attr="in">
<descr>
<p>The node to insert.</p>
</descr>
</param>
<param name="refChild" type="Node" attr="in">
<descr>
<p>The reference node, i.e., the node before which the new node must
be inserted.</p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr>
<p>The node being inserted.</p>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr>
<p>HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does
not allow children of the type of the <code>newChild</code> node, or if the node to insert is one of this node's
<termref def="dt-ancestor">ancestors</termref>.</p>
<p>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created from a different document than the one that created this
node.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if
the parent of the node being inserted is readonly.</p>
<p>NOT_FOUND_ERR: Raised if <code>refChild</code> is not a child of this node.</p>
</descr>
</exception>
</raises>
</method>
<method name="replaceChild" id="ID-785887307">
<descr>
<p>Replaces the child node <code>oldChild</code> with <code>newChild</code> in the list of children, and returns the <code>oldChild</code> node.</p>
<p>If <code>newChild</code> is a <code>DocumentFragment</code> object, <code>oldChild</code> is replaced by all of the <code>DocumentFragment</code> children, which are inserted in the same order. If the <code>newChild</code> is already in the tree, it is first removed.</p>
</descr>
<parameters>
<param name="newChild" type="Node" attr="in">
<descr>
<p>The new node to put in the child list.</p>
</descr>
</param>
<param name="oldChild" type="Node" attr="in">
<descr>
<p>The node being replaced in the list.</p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr>
<p>The node replaced.</p>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr>
<p>HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does
not allow children of the type of the <code>newChild</code> node, or if the node to put in is one of this node's
<termref def="dt-ancestor">ancestors</termref>.</p>
<p>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created from a different document than the one that created this
node.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of
the new node is readonly.</p>
<p>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of this node.</p>
</descr>
</exception>
</raises>
</method>
<method name="removeChild" id="ID-1734834066">
<descr>
<p>Removes the child node indicated by <code>oldChild</code> from the list of children, and returns it.</p>
</descr>
<parameters>
<param name="oldChild" type="Node" attr="in">
<descr>
<p>The node being removed.</p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr>
<p>The node removed.</p>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of this node.</p>
</descr>
</exception>
</raises>
</method>
<method name="appendChild" id="ID-184E7107">
<descr>
<p>Adds the node <code>newChild</code> to the end of the list of children of this node. If the <code>newChild</code> is already in the tree, it is first removed.</p>
</descr>
<parameters>
<param name="newChild" type="Node" attr="in">
<descr>
<p>The node to add.</p>
<p>If it is a <code>DocumentFragment</code> object, the entire contents of the document fragment are moved into the
child list of this node</p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr>
<p>The node added.</p>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr>
<p>HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does
not allow children of the type of the <code>newChild</code> node, or if the node to append is one of this node's
<termref def="dt-ancestor">ancestors</termref>.</p>
<p>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created from a different document than the one that created this
node.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="hasChildNodes" id="ID-810594187">
<descr>
<p>Returns whether this node has any children.</p>
</descr>
<parameters> <!-- No parameters -->
</parameters>
<returns type="boolean">
<descr>
<p> <code>true</code> if this node has any children, <code>false</code> otherwise.</p>
</descr>
</returns>
<raises> <!-- No exceptions -->
</raises>
</method>
<method name="cloneNode" id="ID-3A0ED0A4">
<descr>
<p>Returns a duplicate of this node, i.e., serves as a generic copy
constructor for nodes. The duplicate node has no parent; (<code>parentNode</code> is <code>null</code>.).</p>
<p>Cloning an <code>Element</code> copies all attributes and their values, including those generated by
the XML processor to represent defaulted attributes, but this method does not
copy any text it contains unless it is a deep clone, since the text is
contained in a child <code>Text</code> node. Cloning an <code>Attribute</code> directly, as opposed to be cloned as part of an <code>Element</code> cloning operation, returns a specified attribute (<code>specified</code> is <code>true</code>). Cloning any other type of node simply returns a copy of this
node.</p>
<p>Note that cloning an immutable subtree results in a mutable copy, but
the children of an <code>EntityReference</code> clone are <termref def="dt-readonly-node">readonly</termref>. In
addition, clones of unspecified <code>Attr</code> nodes are specified. And, cloning <code>Document</code>, <code>DocumentType</code>, <code>Entity</code>, and <code>Notation</code> nodes is implementation dependent.</p>
</descr>
<parameters>
<param name="deep" type="boolean" attr="in">
<descr>
<p>If <code>true</code>, recursively clone the subtree under the specified node; if <code>false</code>, clone only the node itself (and its attributes, if it is an <code>Element</code>). </p>
</descr>
</param>
</parameters>
<returns type="Node">
<descr>
<p>The duplicate node.</p>
</descr>
</returns>
<raises> <!-- No exceptions -->
</raises>
</method>
<!-- ****** DOM Level 2 additions ****** -->
<method id="ID-normalize" name="normalize" version="DOM Level 2">
<descr>
<p>Puts all <code>Text</code> nodes in the full depth of the sub-tree underneath this <code>Node</code>, including attribute nodes, into a "normal" form where only structure
(e.g., elements, comments, processing instructions, CDATA sections, and entity
references) separates <code>Text</code> nodes, i.e., there are neither adjacent <code>Text</code> nodes nor empty <code>Text</code> nodes. This can be used to ensure that the DOM view of a document is
the same as if it were saved and re-loaded, and is useful when operations (such
as XPointer <bibref ref="XPointer"/> lookups) that depend on a particular
document tree structure are to be used.</p>
<note>
<p>In cases where the document contains <code>CDATASections</code>, the normalize operation alone may not be sufficient, since XPointers
do not differentiate between <code>Text</code> nodes and <code>CDATASection</code> nodes.</p>
</note>
</descr>
<parameters> <!-- No parameters -->
</parameters>
<returns type="void">
<descr>
<p></p>
</descr>
</returns>
<raises> <!-- No exceptions -->
</raises>
</method>
<method name="isSupported" id="Level-2-Core-Node-supports"
since="DOM Level 2">
<descr>
<p>Tests whether the DOM implementation implements a specific feature and
that feature is supported by this node.</p>
</descr>
<parameters>
<param name="feature" type="DOMString" attr="in">
<descr>
<p>The name of the feature to test. This is the same name which can
be passed to the method <code>hasFeature</code> on <code>DOMImplementation</code>.</p>
</descr>
</param>
<param name="version" type="DOMString" attr="in">
<descr>
<p>This is the version number of the feature to test. In Level 2,
version 1, this is the string "2.0". If the version is not specified,
supporting any version of the feature will cause the method to return <code>true</code>.</p>
</descr>
</param>
</parameters>
<returns type="boolean">
<descr>
<p>Returns <code>true</code> if the specified feature is supported on this node, <code>false</code> otherwise.</p>
</descr>
</returns>
<raises> <!-- No exceptions -->
</raises>
</method>
<attribute readonly="yes" type="DOMString" name="namespaceURI"
id="ID-NodeNSname" since="DOM Level 2">
<descr>
<p>The <termref def="dt-namespaceURI">namespace URI</termref> of this
node, or <code>null</code> if it is unspecified.</p>
<p>This is not a computed value that is the result of a namespace lookup
based on an examination of the namespace declarations in scope. It is merely
the namespace URI given at creation time.</p>
<p>For nodes of any type other than <code>ELEMENT_NODE</code> and <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 method, such as <code>createElement</code> from the <code>Document</code> interface, this is always <code>null</code>.</p>
<note>
<p>Per the <emph>Namespaces in XML</emph> Specification
<bibref ref="Namespaces"/> an attribute does not inherit its namespace from the
element it is attached to. If an attribute is not explicitly given a namespace,
it simply has no namespace.</p>
</note>
</descr>
</attribute>
<attribute type="DOMString" name="prefix" id="ID-NodeNSPrefix"
since="DOM Level 2">
<descr>
<p>The <termref def="dt-namespaceprefix">namespace prefix</termref> of
this node, or <code>null</code> if it is unspecified.</p>
<p>Note that setting this attribute, when permitted, changes the <code>nodeName</code> attribute, which holds the <termref def="dt-qualifiedname">qualified
name</termref>, as well as the <code>tagName</code> and <code>name</code> attributes of the <code>Element</code> and <code>Attr</code> interfaces, when applicable.</p>
<p>Note also that changing the prefix of an attribute that is known to
have a default value, does not make a new attribute with the default value and
the original prefix appear, since the <code>namespaceURI</code> and <code>localName</code> do not change.</p>
<p>For nodes of any type other than <code>ELEMENT_NODE</code> and <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 method, such as <code>createElement</code> from the <code>Document</code> interface, this is always <code>null</code>.</p>
</descr>
<setraises>
<exception name="DOMException">
<descr>
<p>INVALID_CHARACTER_ERR: Raised if the specified prefix contains an
illegal character.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>NAMESPACE_ERR: Raised if the specified <code>prefix</code> is malformed, if the <code>namespaceURI</code> of this node is <code>null</code>, if the specified prefix is "xml" and the <code>namespaceURI</code> of this node is different from "<loc href="&xml-ns;">&xml-ns;</loc>",
if this node is an attribute and the specified prefix is "xmlns" and the <code>namespaceURI</code> of this node is different from "<loc
href="&xmlns-ns;">&xmlns-ns;</loc>", or if this node is an attribute and the <code>qualifiedName</code> of this node is "xmlns" <bibref ref="Namespaces"/>.</p>
</descr>
</exception>
</setraises>
</attribute>
<attribute readonly="yes" type="DOMString" name="localName"
id="ID-NodeNSLocalN" since="DOM Level 2">
<descr>
<p>Returns the local part of the <termref
def="dt-qualifiedname">qualified name</termref> of this node.</p>
<p>For nodes of any type other than <code>ELEMENT_NODE</code> and <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 method, such as <code>createElement</code> from the <code>Document</code> interface, this is always <code>null</code>.</p>
</descr>
</attribute>
<method name="hasAttributes" id="ID-NodeHasAttrs" since="DOM Level 2">
<descr>
<p>Returns whether this node (if it is an element) has any
attributes.</p>
</descr>
<parameters> <!-- No parameters -->
</parameters>
<returns type="boolean">
<descr>
<p><code>true</code> if this node has any attributes, <code>false</code> otherwise.</p>
</descr>
</returns>
<raises> <!-- No exceptions -->
</raises>
</method>
</interface>
@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<interface name="Notation" inherits="Node" id="ID-5431D1B9">
<!-- $Date$ $Revision$ -->
<descr>
<p>This interface represents a notation declared in the DTD. A notation
either declares, by name, the format of an unparsed entity (see <xspecref
href="&xml-spec;#Notations">section 4.7</xspecref>
of the XML 1.0 specification <bibref ref="XML"/>), or is used for formal
declaration of
processing instruction targets (see <xspecref
href="&xml-spec;#sec-pi">section 2.6</xspecref> of the XML 1.0
specification <bibref ref="XML"/>). The <code>nodeName</code> attribute
inherited from
<code>Node</code> is set to the declared name of the notation.</p>
<p>The DOM Level 1 does not support editing <code>Notation</code>
nodes; they are therefore
<termref def="dt-readonly-node">readonly</termref>.</p>
<p>A <code>Notation</code> node does not have any parent.</p>
</descr>
<attribute readonly="yes" name="publicId" type="DOMString" id="ID-54F2B4D0">
<descr><p>The public identifier of this notation. If the
public identifier was not specified, this is <code>null</code>.</p>
</descr>
</attribute>
<attribute readonly="yes" name="systemId" type="DOMString" id="ID-E8AAB1D0">
<descr><p>The system identifier of this notation. If the
system identifier was not specified, this is <code>null</code>.</p>
</descr>
</attribute>
</interface>
+27
View File
@@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ ProcessingInstruction object description ]-->
<!-- $Date$ $Revision$ -->
<interface name="ProcessingInstruction" inherits="Node" id="ID-1004215813">
<descr><p>The <code>ProcessingInstruction</code> interface
represents a &quot;processing instruction&quot;, used in XML
as a way to keep processor-specific information in the text of the
document.</p></descr>
<attribute readonly="yes" type="DOMString" name="target" id="ID-1478689192">
<descr><p>The target of this processing instruction. XML defines this as
being the first <termref def="dt-token">token</termref> following the
markup that begins the processing instruction.</p></descr>
</attribute>
<attribute type="DOMString" name="data" id="ID-837822393">
<descr><p>The content of this processing instruction. This
is from the first non white space character after the target
to the character immediately preceding the <code>?&gt;</code>.</p>
</descr>
<setraises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised when the node is
readonly.</p></descr>
</exception>
</setraises>
</attribute>
</interface>
+48
View File
@@ -0,0 +1,48 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--[ Text object description ]-->
<!-- $Date$ $Revision$ -->
<interface name="Text" inherits="CharacterData" id="ID-1312295772">
<descr>
<p>The <code>Text</code> interface inherits from <code>CharacterData</code> and represents the textual content (termed
<xspecref href="&xml-spec;#syntax">character data</xspecref> in XML) of an <code>Element</code> or <code>Attr</code>. If there is no markup inside an element's content, the text is
contained in a single object implementing the <code>Text</code> interface that is the only child of the element. If there is markup, it
is parsed into the <termref def="dt-infoitem">information items</termref>
(elements, comments, etc.) and <code>Text</code> nodes that form the list of children of the element.</p>
<p>When a document is first made available via the DOM, there is only one <code>Text</code> node for each block of text. Users may create adjacent <code>Text</code> nodes that represent the contents of a given element without any
intervening markup, but should be aware that there is no way to represent the
separations between these nodes in XML or HTML, so they will not (in general)
persist between DOM editing sessions. The <code>normalize()</code> method on <code>Node</code> merges any such adjacent <code>Text</code> objects into a single node for each block of text.</p>
</descr>
<method name="splitText" id="ID-38853C1D">
<descr>
<p>Breaks this node into two nodes at the specified <code>offset</code>, keeping both in the tree as <termref
def="dt-sibling">siblings</termref>. After being split, this node will contain
all the content up to the <code>offset</code> point. A new node of the same type, which contains all the content at
and after the <code>offset</code> point, is returned. If the original node had a parent node, the new
node is inserted as the next <termref def="dt-sibling">sibling</termref> of the
original node. When the <code>offset</code> is equal to the length of this node, the new node has no data.</p>
</descr>
<parameters>
<param name="offset" type="unsigned long" attr="in">
<descr>
<p>The <termref def="dt-16-bit-unit">16-bit unit</termref> offset at
which to split, starting from <code>0</code>.</p>
</descr>
</param>
</parameters>
<returns type="Text">
<descr>
<p>The new node, of the same type as this node.</p>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr>
<p>INDEX_SIZE_ERR: Raised if the specified offset is negative or
greater than the number of 16-bit units in <code>data</code>.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
</descr>
</exception>
</raises>
</method>
</interface>
+181
View File
@@ -0,0 +1,181 @@
<?xml version="1.0" ?>
<!-- $Id$ -->
<!DOCTYPE spec PUBLIC
"-//W3C//DTD Specification V2.1-Based DOM//EN"
"../../../pubtext/xmlspec-v21-dom.dtd" [
<!ENTITY prefix "Core">
<!ENTITY % version SYSTEM "../version.xml">
%version;
<!ENTITY % links SYSTEM "../link-entities.xml">
%links;
<!ENTITY % parts SYSTEM "../part-entities.xml">
%parts;
<!ENTITY options SYSTEM "../options.xml">
]>
<spec>
<!--
*************************************************************************
* FRONT MATTER *
*************************************************************************
-->
&options;
<header>
<title>Document Object Model (DOM) Level 2 Core Specification</title>
<version>1.0</version> <w3c-designation>&doc.prefix;-&doc.date;
</w3c-designation> <w3c-doctype>W3C Recommendation</w3c-doctype> <pubdate>
<day>&date.day;</day> <month>&date.month;</month> <year>&date.year;</year>
</pubdate>
<publoc> <loc href="&this.url;">&this.url;</loc>
&ps.loc;
&pdf.loc;
&txt.loc;
&zip.loc;
</publoc>
<latestloc> <loc href="&latest.url;">&latest.url;</loc> </latestloc>
<prevlocs>
&prev.locs;
</prevlocs>
<authlist>
<author role="editor">
<name>Arnaud Le Hors</name>
<affiliation>W3C team contact until October 1999, then IBM</affiliation>
</author>
<author role="editor">
<name>Philippe Le H&eacute;garet</name>
<affiliation>W3C, team contact (from November 1999)</affiliation>
</author>
<author role="editor"> <name>Lauren Wood</name>
<affiliation>SoftQuad Software Inc., WG Chair</affiliation>
</author>
<author role="editor">
<name>Gavin Nicol</name>
<affiliation>Inso EPS (for DOM Level 1)</affiliation>
</author>
<author role="editor">
<name>Jonathan Robie</name>
<affiliation>Texcel Research and Software AG (for DOM Level 1)</affiliation>
</author>
<author role="editor">
<name>Mike Champion</name>
<affiliation>ArborText and Software AG (for DOM Level 1 from November 20,
1997)</affiliation>
</author>
<author role="editor">
<name>Steve Byrne</name>
<affiliation>JavaSoft (for DOM Level 1 until November 19,
1997)</affiliation>
</author>
</authlist>
<!--
******************************************************
* DOCUMENT ABSTRACT *
******************************************************
-->
<abstract id="id-abstract">
<p>This specification defines the Document Object Model Level 2 Core, a platform-
and language-neutral interface that allows programs and scripts to dynamically
access and update the content and structure of documents. The Document
Object Model Level 2 Core builds on the Document Object Model Level 1 Core.</p>
<p>The DOM Level 2 Core is made of a set of core interfaces to create and
manipulate the structure and contents of a document. The Core also contains
specialized interfaces dedicated to XML.</p>
</abstract>
&status;
<sourcedesc>
<p>Created in electronic form.</p>
</sourcedesc>
<langusage>
<language id="en">English</language>
</langusage>
<revisiondesc>
<p>$Revision$</p>
</revisiondesc>
<?GENERATE-TOC?>
</header>
<front>
&toc;
&copyright;
&introduction;
</front>
<body>
&core;
</body>
<!--
*************************************************************************
* BACK MATTER *
*************************************************************************
-->
<back>
&core-changes;
&i18nfunctions;
<div1 role="idl" id="idl">
<head>IDL Definitions</head>
<p>This appendix contains the complete OMG IDL <bibref ref='OMGIDL'/> for
the Level 2 Document Object Model Core definitions.</p>
<p>The IDL files are also available as: <loc
href="idl.zip">&this.url;/idl.zip</loc></p>
<!--
******************************************************
| CORE OMG IDL DEFINITIONS |
******************************************************
-->
<?GENERATE-IDL Core dom w3c.org?>
</div1>
<div1 role="java-binding" id="java-binding">
<head>Java Language Binding</head>
<p>This appendix contains the complete Java Language <bibref ref='Java'/>
binding for the Level 2 Document Object Model Core.</p>
<p>The Java files are also available as <loc
href="java-binding.zip">&this.url;/java-binding.zip</loc></p>
<!--
******************************************************
| CORE JAVA BINDINGS |
******************************************************
-->
<?GENERATE-JAVA Core org.w3c dom?>
</div1>
<div1 role="ecma-binding" id="ecma-binding">
<head>ECMAScript Language Binding</head>
<p>This appendix contains the complete ECMAScript <bibref
ref='ECMAScript'/> binding for the Level 2 Document Object Model Core
definitions.</p>
<note>
<p>
Exceptions handling is only supported by ECMAScript implementation
conformant with the Standard ECMA-262 3rd. Edition (<bibref
ref="ECMAScript"/>).
</p>
</note>
<!--
******************************************************
| CORE ECMASCRIPT BINDINGS |
******************************************************
-->
<?GENERATE-ECMA Core?>
</div1>
&contributors;
&glossary;
&references;
&index;
</back>
</spec>
+149
View File
@@ -0,0 +1,149 @@
<?xml version="1.0" encoding='UTF-8'?>
<!-- $Id$ -->
<!--
*************************************************************************
* BEGINNING OF DOM I18N *
*************************************************************************
-->
<div1 id="i18n">
<head>Accessing code point boundaries</head>
<orglist>
<member>
<name>Mark Davis</name>
<affiliation>IBM</affiliation>
</member>
<member>
<name>Lauren Wood</name>
<affiliation>SoftQuad Software Inc.</affiliation>
</member>
</orglist><?GENERATE-MINI-TOC?>
<div2 id="i18n-introduction">
<head>Introduction</head>
<p>
This appendix is an informative, not a normative, part of the Level 2 DOM
specification.
</p>
<p>
Characters are represented in Unicode by numbers called <i>code
points</i> (also called <i>scalar values</i>). These numbers can range
from 0 up to 1,114,111 = 10FFFF<sub>16</sub> (although some of these values are
illegal). Each code point can be directly encoded with a 32-bit code unit.
This encoding is termed UCS-4 (or UTF-32).
The DOM specification, however, uses UTF-16, in which the most frequent
characters (which have values less than FFFF<sub>16</sub>) are represented
by a single 16-bit code unit, while characters above FFFF<sub>16</sub>
use a special pair of code units called a <i>surrogate pair</i>. For more information,
see <bibref ref="Unicode"/> or the Unicode Web site.
</p>
<p>
While indexing by code points as opposed to code units is not
common in programs, some specifications such as XPath (and therefore XSLT
and XPointer) use code point
indices. For interfacing with such formats it is recommended
that the programming language provide string processing methods for
converting code point indices to code unit indices and back. Some
languages do not provide these functions natively; for these it is
recommended that the native <code>String</code> type that is bound to
<code>DOMString</code> be extended to enable this conversion. An example
of how such an API might look is supplied below.
</p>
<note>
<p>
Since these methods are supplied as an illustrative example of the type
of functionality that is required, the names of the methods,
exceptions, and interface may differ from those given here.
</p>
</note>
</div2>
<div2 id="i18n-methods">
<head>Methods</head>
<definitions>
<interface id="i18n-methods-StringExtend" name="StringExtend">
<descr>
<p>Extensions to a language's native String class or interface</p>
</descr>
<method id="i18n-methods-StringExtend-findOffset16" name="findOffset16">
<descr>
<p>Returns the UTF-16 offset that corresponds to a UTF-32 offset.
Used for random access.</p>
<note>
<p>
You can always round-trip from a UTF-32 offset to a UTF-16
offset and back. You can round-trip from a UTF-16 offset to
a UTF-32 offset and back if and only if the offset16 is not
in the middle of a surrogate pair. Unmatched surrogates
count as a single UTF-16 value.
</p>
</note>
</descr>
<parameters>
<param name="offset32" type="int" attr="in">
<descr>
<p>
UTF-32 offset.
</p>
</descr>
</param>
</parameters>
<returns type="int">
<descr>
<p>UTF-16 offset</p>
</descr>
</returns>
<raises>
<exception name="StringIndexOutOfBoundsException">
<descr>
<p>
if <code>offset32</code> is out of bounds.
</p>
</descr>
</exception>
</raises>
</method>
<method id="i18n-methods-StringExtend-findOffset32" name="findOffset32">
<descr>
<p>
Returns the UTF-32 offset corresponding to a UTF-16 offset. Used
for random access. To find the UTF-32 length of a string, use:
<eg>len32 = findOffset32(source, source.length());</eg>
</p>
<note>
<p>
If the UTF-16 offset is into the middle of a surrogate pair,
then the UTF-32 offset of the <emph>end</emph> of the pair is
returned; that is, the index of the char after the end of the
pair. You can always round-trip from a UTF-32 offset to a UTF-16
offset and back. You can round-trip from a UTF-16 offset to a
UTF-32 offset and back if and only if the offset16 is not in
the middle of a surrogate pair. Unmatched surrogates count as a
single UTF-16 value.
</p>
</note>
</descr>
<parameters>
<param attr="in" type="int" name="offset16">
<descr>
<p>UTF-16 offset</p>
</descr>
</param>
</parameters>
<returns type="int">
<descr>
<p>UTF-32 offset</p>
</descr>
</returns>
<raises>
<exception name="StringIndexOutOfBoundsException">
<descr>
<p>if offset16 is out of bounds.</p>
</descr>
</exception>
</raises>
</method>
</interface>
</definitions>
</div2>
</div1>
+431
View File
@@ -0,0 +1,431 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id$ -->
<!--
*************************************************************************
* BEGINNING OF DOM INTRODUCTION *
*************************************************************************
-->
<div1 id="Introduction">
<head>What is the Document Object Model?</head>
<orglist role="editors">
<member>
<name>Philippe Le H&eacute;garet</name>
<affiliation>W3C</affiliation>
</member>
<member>
<name>Lauren Wood</name>
<affiliation>SoftQuad Software Inc., WG Chair</affiliation>
</member>
<member>
<name>Jonathan Robie</name>
<affiliation>Texcel (for DOM Level 1)</affiliation>
</member>
</orglist>
<div2 id="ID-E7C3082">
<head>Introduction</head>
<p>The Document Object Model (DOM) is an application programming interface
(<termref def="dt-API">API</termref>) for valid <termref def="dt-HTML">HTML</termref> and
well-formed <termref def="dt-XML">XML</termref> documents. It defines the logical structure of documents and
the way a document is accessed and manipulated. In the DOM specification,
the term "document" is used in the broad sense - increasingly, XML is being used as a
way of representing many different kinds of information that may
be stored in diverse systems, and much of this would traditionally
be seen as data rather than as documents. Nevertheless, XML presents
this data as documents, and the DOM may be used to manage this data.</p>
<p>With the Document
Object Model, programmers can build documents, navigate
their structure, and add, modify, or delete elements and content.
Anything found in an HTML or XML document can be accessed,
changed, deleted, or added using the Document Object Model,
with a few exceptions - in particular, the DOM <termref
def="dt-interface">interfaces</termref> for
the XML internal and external subsets have not yet been specified.</p>
<p>As a W3C specification, one important objective for the Document
Object Model is to provide a standard programming interface that
can be used in a wide variety of environments and <termref
def="dt-application">applications</termref>.
The DOM is designed to be used with any programming
language. In order to provide a precise, language-independent
specification of the DOM interfaces, we have chosen to define
the specifications in Object Management Group (OMG) IDL <bibref
ref="OMGIDL"/>, as defined in the CORBA 2.3.1 specification <bibref
ref="CORBA"/>. In addition to the OMG IDL specification, we provide
<termref def="dt-lang-binding">language bindings</termref> for Java <bibref ref="Java"/> and ECMAScript <bibref
ref="ECMAScript"/> (an industry-standard scripting
language based on JavaScript <bibref ref="JavaScript"/> and JScript
<bibref ref='JScript'/>).</p>
<note><p>OMG IDL is used only as a language-independent and
implementation-neutral way to specify <termref def="dt-interface">interfaces</termref>. Various other
IDLs could have been used (<bibref ref="COM"/>, <bibref
ref="JavaIDL"/>, <bibref ref="MSIDL"/>, ...). In general, IDLs
are designed for specific computing environments. The Document Object
Model can be implemented in any computing environment, and does not
require the object binding runtimes generally associated with
such IDLs.
</p></note>
</div2>
<div2 id="ID-E7C30821">
<head>What the Document Object Model is</head>
<p>The DOM is a programming <termref def="dt-API">API</termref> for documents.
It is based on an object structure that closely resembles the structure of the
documents it <termref def="dt-model">models</termref>. For instance, consider this table, taken
from an HTML document: </p>
<eg role="code">
&lt;TABLE&gt;
&lt;TBODY&gt;
&lt;TR&gt;
&lt;TD&gt;Shady Grove&lt;/TD&gt;
&lt;TD&gt;Aeolian&lt;/TD&gt;
&lt;/TR&gt;
&lt;TR&gt;
&lt;TD&gt;Over the River, Charlie&lt;/TD&gt;
&lt;TD&gt;Dorian&lt;/TD&gt;
&lt;/TR&gt;
&lt;/TBODY&gt;
&lt;/TABLE&gt;
</eg>
<p>A graphical representation of the DOM of the example table is:
<graphic source="./images/table.gif" alt="graphical representation of the
DOM of the example table"/>
</p>
<p>In the DOM, documents have a logical
structure which is very much like a tree; to be more precise, which is
like a &quot;forest&quot; or &quot;grove&quot;,
which can contain more than one tree. Each document contains zero or one
doctype nodes, one root element node, and zero or more comments
or processing instructions; the root element serves as the root
of the element tree for the document. However, the DOM
does not specify that documents must be <emph>implemented</emph> as a
tree or a grove<!--but not the same as an sgml grove-->, nor
does it specify how the relationships among objects be
implemented. The DOM is a logical model that may be implemented in any
convenient manner. In this
specification, we use the term <emph>structure model</emph> to
describe the tree-like representation of a document.
We also use the term "tree" when referring to the arrangement of
those information items which can be reached by using "tree-walking"
methods; (this does not include attributes).
One important property of DOM structure models
is <emph>structural isomorphism</emph>: if any two Document
Object Model implementations are used to create a representation
of the same document, they will create the same structure model,
in accordance with the XML Information Set <bibref ref="InfoSet"/>.</p>
<note><p>There may be some variations depending on the parser being
used to build the DOM. For instance, the DOM may not contain
whitespaces in element content if the parser discards them.</p>
</note>
<p>The name &quot;Document Object Model&quot; was chosen because
it is an &quot;<termref def="dt-object-model">object model</termref>&quot; in the traditional
object oriented design sense: documents are modeled using
objects, and the model encompasses not only the structure of a
document, but also the behavior of a document and the objects
of which it is composed. In other words, the nodes in the
above diagram do not represent a data structure, they
represent objects, which have functions and identity. As an
object model, the DOM identifies:</p>
<ulist>
<item><p>the interfaces and objects used to represent and manipulate
a document</p></item>
<item><p>the semantics of these interfaces and objects - including
both behavior and attributes</p></item>
<item><p>the relationships and collaborations among these interfaces
and objects</p></item>
</ulist>
<p>The structure of SGML documents has traditionally been
represented by an abstract <termref def="dt-datamodel">data model</termref>, not by an object model.
In an abstract <termref def="dt-datamodel">data model</termref>, the model is centered around the
data. In object oriented programming languages, the data itself
is encapsulated in objects that hide the data, protecting it
from direct external manipulation. The functions associated with
these objects determine how the objects may be manipulated, and
they are part of the object model.</p>
</div2>
<div2 id="ID-E7C30822">
<head>What the Document Object Model is not</head>
<p>This section is designed to give a more precise understanding
of the DOM by distinguishing it from other
systems that may seem to be like it.</p>
<ulist>
<item><p>The Document Object Model is not a binary specification.
DOM programs written in the same language binding will be
source code compatible across platforms, but the DOM
does not define any form of binary interoperability.</p></item>
<item><p>The Document Object Model is not a way of persisting objects
to XML or HTML. Instead of specifying how objects may be
represented in XML, the DOM specifies how
XML and HTML documents are represented as objects, so that
they may be used in object oriented programs.</p></item>
<item><p>The Document Object Model is not a set of data structures;
it is an <termref def="dt-object-model">object model</termref> that specifies interfaces. Although this
document contains diagrams showing parent/child relationships,
these are logical relationships defined by the programming
interfaces, not representations of any particular internal
data structures.</p></item>
<item><p>The Document Object Model does not define what information in a
document is relevant or how information in a document is
structured. For XML, this is specified by the W3C XML Information Set
<bibref ref="InfoSet"/>. The DOM is simply an <termref def="dt-API">API</termref> to this information
set.</p></item>
<item><p>The Document Object Model, despite its name, is not a
competitor to the Component Object Model (COM). COM, like
CORBA, is a language independent way to specify interfaces and
objects; the DOM is a set of interfaces and
objects designed for managing HTML and XML documents. The DOM
may be implemented using language-independent systems like COM
or CORBA; it may also be implemented using language-specific
bindings like the Java or ECMAScript bindings specified in
this document.</p></item>
</ulist>
</div2>
<div2 id="ID-E7C30823">
<head>Where the Document Object Model came from</head>
<p>The DOM originated as a specification to
allow JavaScript scripts and Java programs to be portable among
Web browsers. "Dynamic HTML" was the immediate ancestor of the
Document Object Model, and it was originally thought of largely
in terms of browsers. However, when the DOM
Working Group was formed at W3C, it was also joined by vendors in other
domains, including HTML or XML editors and document
repositories. Several of these vendors had worked with SGML
before XML was developed; as a result, the DOM
has been influenced by SGML Groves and the HyTime standard. Some
of these vendors had also developed their own object models for
documents in order to provide an API for SGML/XML
editors or document repositories, and these object models have
also influenced the DOM.</p>
</div2>
<div2 id="ID-E7C30824"><head>Entities and the DOM Core</head>
<p>In the fundamental DOM interfaces, 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 entity's replacement.
For example, in:
</p>
<eg role="code">
&lt;p&gt;This is a dog &amp;amp; a cat&lt;/p&gt;
</eg>
<p>
the "&amp;amp;" will be replaced by the character "&amp;", and the text
in the P element will form a single continuous sequence of
characters. Since numeric character references and pre-defined entities
are not recognized as such in CDATA sections, or in the SCRIPT and STYLE
elements in HTML, they are not replaced by the single character they
appear to refer to. If the example above were enclosed in a CDATA
section, the "&amp;amp;" would not be replaced by "&amp;"; neither would
the &lt;p&gt; be recognized as a start tag. The representation of general
entities, both internal and external, are defined within the
extended (XML) interfaces of DOM Level 1 <bibref ref='DOM-Level-1'/>.</p>
<p>
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. Also, <termref
def="dt-implementation">implementations</termref> should be
aware of the fact that serialization into a character encoding
("charset") that does not fully cover ISO 10646 may fail if there are
characters in markup or CDATA sections that are not present in the
encoding.</p>
</div2>
<div2 id="ID-Conformance">
<head>Conformance</head>
<p>
This section explains the different levels of conformance to DOM Level 2.
DOM Level 2 consists of 14 modules. It is possible to conform to DOM
Level 2, or to a DOM Level 2 module.
</p>
<p>
An implementation is DOM Level 2 conformant if it supports the Core
module defined in this document (see <specref ref="ID-BBACDC08"/>). An
implementation conforms to a DOM Level 2 module if it supports all the
interfaces for that module and the associated semantics.
</p>
<p>
Here is the complete list of DOM Level 2.0 modules and the features used
by them. Feature names are case-insensitive.
</p>
<glist>
<gitem>
<label>Core module</label>
<def>
<p>
defines the feature <xspecref
href="core.html#ID-BBACDC08">"Core"</xspecref>.
</p>
</def>
</gitem>
<gitem>
<label>XML module</label>
<def>
<p>
defines the feature <xspecref
href="core.html#ID-E067D597">"XML"</xspecref>.
</p>
</def>
</gitem>
<gitem>
<label>HTML module</label>
<def>
<p>defines the feature "HTML". (see <bibref ref="DOMHTML-inf"/>).</p>
<note>
<p>At time of publication, this DOM Level 2 module is not yet a W3C Recommendation.</p>
</note>
</def>
</gitem>
<gitem>
<label>Views module</label>
<def>
<p>defines the feature <xspecref
href='&views.latest.url;/views.html'>"Views"</xspecref> in <bibref ref="DOMViews-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>Style Sheets module</label>
<def>
<p>defines the feature <xspecref
href='&style.latest.url;/stylesheets.html'>"StyleSheets"</xspecref> in <bibref ref="DOMStyleSheets-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>CSS module</label>
<def>
<p>defines the feature <xspecref
href='&style.latest.url;/css.html'>"CSS"</xspecref> in <bibref ref="DOMCSS-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>CSS2 module</label>
<def>
<p>defines the feature <xspecref
href='&style.latest.url;/css.html'>"CSS2"</xspecref> in <bibref ref="DOMCSS-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>Events module</label>
<def>
<p>defines the feature <xspecref
href='&events.latest.url;/events.html'>"Events"</xspecref> in <bibref ref="DOMEvents-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>User interface Events module</label>
<def>
<p>defines the feature <xspecref
href='&events.latest.url;/events.html'>"UIEvents"</xspecref> in <bibref ref="DOMEvents-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>Mouse Events module</label>
<def>
<p>defines the feature <xspecref
href='&events.latest.url;/events.html'>"MouseEvents"</xspecref> in <bibref ref="DOMEvents-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>Mutation Events module</label>
<def>
<p>defines the feature <xspecref
href='&events.latest.url;/events.html'>"MutationEvents"</xspecref> in <bibref ref="DOMEvents-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>HTML Events module</label>
<def>
<p>defines the feature <xspecref
href='&events.latest.url;/events.html'>"HTMLEvents"</xspecref> in <bibref ref="DOMEvents-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>Range module</label>
<def>
<p>defines the feature <xspecref
href='&traversal-range.latest.url;/ranges.html'>"Range"</xspecref> in <bibref ref="DOMRange-inf"/>.</p>
</def>
</gitem>
<gitem>
<label>Traversal module</label>
<def>
<p>defines the feature <xspecref
href='&traversal-range.latest.url;/traversal.html'>"Traversal"</xspecref> in <bibref ref="DOMTraversal-inf"/>.</p>
</def>
</gitem>
</glist>
<p>
A DOM implementation must not return <code>"true"</code> to the
<code>hasFeature(feature, version)</code> <termref
def="dt-method">method</termref> of the <code>DOMImplementation</code>
interface for that feature unless the implementation conforms to that
module. The <code>version</code> number for all features used in DOM
Level 2.0 is "2.0".
</p>
</div2>
<div2 id="ID-E7C30826"><head>DOM Interfaces and DOM Implementations</head>
<p>The DOM specifies interfaces which may be used to manage XML or
HTML documents. It is important to realize that these interfaces
are an abstraction - much like "abstract base classes" in C++,
they are a means of specifying a way to access and manipulate an
application's internal representation of a document. Interfaces
do not imply a particular concrete
implementation. Each DOM application is free to maintain
documents in any convenient representation, as long as the
interfaces shown in this specification are supported. Some
DOM implementations will be existing programs that use the
DOM interfaces to access software written long before the
DOM specification existed. Therefore, the DOM is designed
to avoid implementation dependencies; in particular,</p>
<olist>
<item><p>Attributes defined in the IDL do not imply concrete
objects which must have specific data members - in the
language bindings, they are translated to a pair of
get()/set() functions, not to a data member. Read-only
attributes have only a get() function in the language
bindings. </p>
</item>
<item><p>DOM applications may provide additional interfaces
and objects not found in this specification and still be
considered DOM conformant.</p></item>
<item><p>Because we specify interfaces and not the actual
objects that are to be created, the DOM cannot know what
constructors to call for an implementation. In general,
DOM users call the createX() methods on the Document
class to create document structures, and DOM
implementations create their own internal representations
of these structures in their implementations of the
createX() functions.
</p></item>
</olist>
<p>
The Level 1 interfaces were extended to provide both Level 1 and Level 2
functionality.
</p>
<p>
DOM implementations in languages other than Java or ECMAScript may
choose bindings that are appropriate and natural for their language and
run time environment. For example, some systems may need to create a
Document2 class which inherits from Document and contains the new methods
and attributes.
</p>
<p>DOM Level 2 does not specify multithreading mechanisms.</p>
</div2>
</div1>
<!--
*************************************************************************
* END OF DOM INTRODUCTION *
*************************************************************************
-->