This document is also available in these non-normative formats: PostScript file, PDF file, plain text, ZIP file, and single HTML file.
Copyright ©2002 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This specification defines the Document Object Model Load and Save Level 3, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This is a W3C Working Draft for review by W3C members and other interested parties. This DOM module has been dissociated from the Abstract Schema DOM module since the modules were independent and the latter is no longer a work in progress.
It is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by, or the consensus of, either W3C or members of the DOM working group.
Comments on this document are invited and are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.
This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM WG members.
Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.
Copyright © 2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
This document is published under the W3C Document Copyright Notice and License. The bindings within this document are published under the W3C Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java language binding, the package names can no longer be in the 'org.w3c' package.
Note: This section is a copy of the W3C Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-documents-19990405.
Copyright © 1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/
Public documents on the W3C site are provided by the copyright holders under the following license. The software or Document Type Definitions (DTDs) associated with W3C specifications are governed by the Software Notice. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:
When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.
No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.
Note: This section is a copy of the W3C Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720
Copyright © 1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/
This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
This section defines a set of interfaces for loading and saving
document objects as defined in [DOM Level 3 Core]. The functionality
specified in this section (the Load and Save
functionality) is sufficient to allow software developers and web
script authors to load and save XML content inside conforming
products. The DOM Load and Save API also allows filtering of
XML content using only DOM API calls; access and manipulation of
the Document
is defined in [DOM Level 3
Core].
The proposal for loading is influenced by the Java APIs for XML Processing [JAXP] and by SAX2 [SAX].
The list of interfaces involved with the Loading and Saving XML documents is:
DOMImplementationLS
-- A new DOMImplementation
interface that provides the
factory methods for creating the objects required for loading and
saving.DOMBuilder
-- A
parser interface.DOMInputSource
-- Encapsulate information about the XML document to be
loaded.DOMEntityResolver
-- During loading, provides a way for applications to redirect
references to external entities.DOMBuilderFilter
-- Provide the ability to examine and optionally remove Element
nodes as they are being processed during the parsing of a
document.DOMWriter
-- An
interface for writing out or serializing DOM documents.DocumentLS
--
Provides a client or browser style interface for loading and
saving.ParseErrorEvent
-- ParseErrorEvent is the event
that is fired if there's an error in the XML document being parsed
using the methods of DocumentLS.To ensure interoperability, the DOM Load and Save specifies the following:
A DOMInputStream
represents a reference to a byte stream source of an XML input.
typedef Object DOMInputStream;
Note: Even though the DOM uses the type DOMInputStream
,
bindings may use different types. For example, in Java DOMInputStream
is
bound to the java.io.InputStream
type, while in
ECMAScript DOMInputStream
is
bound to Object
.
To ensure interoperability, the DOM Load and Save specifies the following:
A DOMOutputStream
represents a byte stream destination for the XML output.
typedef Object DOMOutputStream;
Note: Even though the DOM uses the type DOMOutputStream
,
bindings may use different types. For example, in Java DOMOutputStream
is bound to the java.io.OutputStream
type, while in
ECMAScript DOMOutputStream
is bound to Object
.
To ensure interoperability, the DOM Load and Save specifies the following:
A DOMReader
represents a character stream for the XML input.
typedef Object DOMReader;
Note: Even though the DOM uses the type DOMReader
, bindings may
use different types. For example, in Java DOMReader
is bound to
the java.io.Reader
type, while in ECMAScript DOMReader
is NOT bound, and therefore as no recommended meaning in
ECMAScript.
The interface within this section is considered fundamental, and must be fully implemented by all conforming implementations of the DOM Load and Save module.
DOMImplementationLS
contains the factory methods
for creating objects that implement the DOMBuilder
(parser)
and DOMWriter
(serializer) interfaces.
The expectation is that an instance of the
DOMImplementationLS
interface can be obtained by using
binding-specific casting methods on an instance of the
DOMImplementation
interface or, if the
Document
supports the feature "Core"
version "3.0"
defined in [DOM Level 3
Core], by using the method Node.getInterface
with
parameter values "LS-Load"
and "3.0"
(respectively).
interface DOMImplementationLS { // DOMIMplementationLSMode const unsigned short MODE_SYNCHRONOUS = 1; const unsigned short MODE_ASYNCHRONOUS = 2; DOMBuilder createDOMBuilder(in unsigned short mode, in DOMString schemaType) raises(DOMException); DOMWriter createDOMWriter(); DOMInputSource createDOMInputSource(); };
An integer indicating which type of mode this is.
MODE_ASYNCHRONOUS
DOMBuilder
.MODE_SYNCHRONOUS
DOMBuilder
.createDOMBuilder
DOMBuilder
. The
newly constructed parser may then be configured by means of its
setFeature
method, and used to parse documents by
means of its parse
method.
mode
of type unsigned
short
mode
argument is either
MODE_SYNCHRONOUS
or MODE_ASYNCHRONOUS
, if
mode
is MODE_SYNCHRONOUS
then the DOMBuilder
that is created will operate in synchronous mode, if it's
MODE_ASYNCHRONOUS
then the DOMBuilder
that is
created will operate in asynchronous mode.schemaType
of type
DOMString
Document
using the newly
created DOMBuilder
. Note
that no lexical checking is done on the absolute URI. In order to
create a DOMBuilder
for any
kind of schema types (i.e. the DOMBuilder will be free to use any
schema found), use the value null
.
Note: For W3C XML Schema [XML Schema Part 1],
applications must use the value
"http://www.w3.org/2001/XMLSchema"
. For XML DTD [XML 1.0],
applications must use the value
"http://www.w3.org/TR/REC-xml"
. Other Schema languages
are outside the scope of the W3C and therefore should recommend an
absolute URI in order to use this method.
The newly created Note: By default, the newly created |
|
NOT_SUPPORTED_ERR: Raised if the requested mode or schema type is not supported. |
createDOMInputSource
DOMInputSource
.
The newly created |
createDOMWriter
DOMWriter
object. DOMWriter
s are used
to serialize a DOM tree back into an XML document.
The newly created Note: By default, the newly created |
The DocumentLS
interface provides a mechanism by
which the content of a document can be replaced with the DOM tree
produced when loading a URI, or parsing a string. The expectation
is that an instance of the DocumentLS
interface can be
obtained by using binding-specific casting methods on an instance
of the Document
interface or, if the
Document
supports the feature "Core"
version "3.0"
defined in [DOM Level 3
Core], by using the method Node.getInterface
with
parameter values "LS-Load"
and "3.0"
(respectively).
interface DocumentLS { attribute boolean async; // raises(DOMException) on setting void abort(); boolean load(in DOMString uri); boolean loadXML(in DOMString source); DOMString saveXML(in Node snode) raises(DOMException); };
async
of type
boolean
true
the load method returns control to the caller before the document
has completed loading. The default value of this attribute is
false
.
false
but we
need to check with Mozilla and IE.
|
NOT_SUPPORTED_ERR: Raised if the implementation doesn't support the mode the attribute is being set to. |
abort
load
being invoked the loading
and parsing is immediately aborted. The possibly partial result of
parsing the document is discarded and the document is cleared.
load
ParseErrorEvent
). If this method is called on a
document that is currently loading, the current load is interrupted
and the new URI load is initiated.DOMBuilder
interface are assumed to have their default values with the
exception that the feature "entities" is "false".
uri
of type
DOMString
|
If async is set to |
loadXML
DOMBuilder
interface are assumed to have their default values when invoking
this method.
source
of type
DOMString
|
|
saveXML
DOMWriter
interface
are assumed to have their default values when invoking this method.
snode
of type
Node
null
the whole document is serialized, if it's
non-null the given node is serialized.
|
The serialized document or |
|
WRONG_DOCUMENT_ERR: Raised if the node passed in as the node parameter is from an other document. |
A DOM application may use the hasFeature(feature,
version)
method of the DOMImplementation
interface with parameter values "LS-Load" and "3.0" (respectively)
to determine whether or not these interfaces are supported by the
implementation. In order to fully support them, an implementation
must also support the "Core" feature defined in the DOM Level 3
Core specification [DOM Level 3 Core].
A DOM application may use the hasFeature(feature,
version)
method of the DOMImplementation
interface with parameter values "LS-Load-Async" and "3.0"
(respectively) to determine whether or not the asynchronous mode is
supported by the implementation. In order to fully support the
asyncrhonous mode, an implementation must also support the
"LS-Load" feature defined in this section.
Please, refer to additional information about conformance in the DOM Level 3 Core specification [DOM Level 3 Core].
This interface represents a single input source for an XML entity.
This interface allows an application to encapsulate information about an input source in a single object, which may include a public identifier, a system identifier, a byte stream (possibly with a specified encoding), and/or a character stream.
The exact definitions of a byte stream and a character stream are binding dependent.
There are two places that the application will deliver this
input source to the parser: as the argument to the
parse
method, or as the return value of the DOMEntityResolver.resolveEntity
method.
The DOMBuilder
will use
the DOMInputSource
object to determine how to read XML
input. If there is a character stream available, the parser will
read that stream directly; if not, the parser will use a byte
stream, if available; if neither a character stream nor a byte
stream is available, the parser will attempt to open a URI
connection to the resource identified by the system identifier.
A DOMInputSource
object belongs to the application:
the parser shall never modify it in any way (it may modify a copy
if necessary).
Note: Even though all attributes in this interface are writable the DOM implementation is expected to never mutate a DOMInputSource.
interface DOMInputSource { attribute DOMInputStream byteStream; attribute DOMReader characterStream; attribute DOMString stringData; attribute DOMString encoding; attribute DOMString publicId; attribute DOMString systemId; attribute DOMString baseURI; };
baseURI
of type
DOMString
byteStream
of type DOMInputStream
characterStream
of
type DOMReader
encoding
of type
DOMString
publicId
of type
DOMString
stringData
of type
DOMString
systemId
of type
DOMString
This interface represents a load event object that signals the completion of a document load.
interface LSLoadEvent : events::Event { readonly attribute Document newDocument; readonly attribute DOMInputSource inputSource; };
inputSource
of type DOMInputSource
,
readonlynewDocument
of type
Document
, readonlyThis interface represents a progress event object that notifies
the application about progress as a document is parsed. It extends
the Event
interface defined in [DOM Level 3
Events].
interface LSProgressEvent : events::Event { readonly attribute DOMInputSource inputSource; readonly attribute unsigned long position; readonly attribute unsigned long totalSize; };
inputSource
of type DOMInputSource
,
readonlyposition
of type
unsigned long
, readonlytotalSize
of type
unsigned long
, readonlyDOMEntityResolver
Provides a way for applications
to redirect references to external entities.
Applications needing to implement customized handling for
external entities must implement this interface and register their
implementation by setting the entityResolver
attribute
of the DOMBuilder
.
The DOMBuilder
will
then allow the application to intercept any external entities
(including the external DTD subset and external parameter entities)
before including them.
Many DOM applications will not need to implement this interface, but it will be especially useful for applications that build XML documents from databases or other specialized input sources, or for applications that use URNs.
Note: DOMEntityResolver
is based on the SAX2
[SAX]
EntityResolver
interface.
interface DOMEntityResolver { DOMInputSource resolveEntity(in DOMString publicId, in DOMString systemId, in DOMString baseURI); };
resolveEntity
DOMBuilder
will
call this method before opening any external entity except the
top-level document entity (including the external DTD subset,
external entities referenced within the DTD, and external entities
referenced within the document element); the application may
request that the DOMBuilder
resolve
the entity itself, that it use an alternative URI, or that it use
an entirely different input source.DOMBuilder
must
resolve it fully before reporting it to the application through
this interface.
publicId
of type
DOMString
null
if none was supplied.systemId
of type
DOMString
baseURI
of type
DOMString
null
if there is no base URI.
A |
DOMBuilderFilter
s provide applications the ability
to examine nodes as they are being constructed during a parse. As
each node is examined, it may be modified or removed, or the entire
parse may be terminated early.
At the time any of the filter methods are called by the parser,
the owner Document and DOMImplementation objects exist and are
accessible. The document element is never passed to the
DOMBuilderFilter
methods, i.e. it is not possible to
filter out the document element. The Document
,
DocumentType
, Notation
, and
Entity
nodes are not passed to the filter.
All validity checking while reading a document occurs on the source document as it appears on the input stream, not on the DOM document as it is built in memory. With filters, the document in memory may be a subset of the document on the stream, and its validity may have been affected by the filtering.
All default content, including default attributes, must be passed to the filter methods.
Any exception raised in the filter are ignored by the DOMBuilder
.
interface DOMBuilderFilter { // Constants returned by startElement and acceptNode const short FILTER_ACCEPT = 1; const short FILTER_REJECT = 2; const short FILTER_SKIP = 3; const short FILTER_INTERRUPT = 4; unsigned short startElement(in Element elt); unsigned short acceptNode(in Node enode); readonly attribute unsigned long whatToShow; };
Constants returned by startElement
and
acceptNode
.
FILTER_ACCEPT
FILTER_INTERRUPT
FILTER_REJECT
FILTER_SKIP
whatToShow
of type
unsigned long
, readonlyDOMBuilder
what
types of nodes to show to the filter. See NodeFilter
for definition of the constants. The constant
SHOW_ATTRIBUTE
is meaningless here, attribute nodes
will never be passed to a DOMBuilderFilter
.acceptNode
enode
of type
Node
|
|
startElement
Element
start tag has been scanned, but before
the remainder of the Element
is processed. The intent
is to allow the element, including any children, to be efficiently
skipped. Note that only element nodes are passed to the
startElement
function.startElement
for filtering
will include all of the Element's attributes, but none of the
children nodes. The Element may not yet be in place in the document
being constructed (it may not have a parent node.)startElement
filter function may access or change
the attributes for the Element. Changing Namespace declarations
will have no effect on namespace resolution by the parser.elt
of type
Element
|
Returning any other values will result in unspecified behavior. |
A interface to an object that is able to build a DOM tree from various input sources.
DOMBuilder
provides an API for parsing XML
documents and building the corresponding DOM document tree. A
DOMBuilder
instance is obtained from the DOMImplementationLS
interface by invoking its createDOMBuilder
method.
As specified in [DOM Level 3 Core], when a document is first made available via the DOMBuilder:
Text
node for each block of
text. The Text
nodes are into "normal" form: only
structure (e.g., elements, comments, processing instructions, CDATA
sections, and entity references) separates Text
nodes,
i.e., there are neither adjacent Text
nodes nor empty
Text
nodes.value
and
nodeValue
attributes of an Attr
node
initially return the XML
1.0 normalized value. However, if the features
validate-if-schema
and
datatype-normalization
are set to true
,
depending on the attribute normalization used, the attribute values
may differ from the ones obtained by the XML 1.0 attribute
normalization. If the feature
datatype-normalization
is not set to
true
, the XML 1.0 attribute normalization is
guaranteed to occur, and if attributes list does not contain
namespace declarations, the attributes
attribute on
Element
node represents the property [attributes]
defined in [XML Information set] .
datatype-normalization
is set to
true
.Asynchronous DOMBuilder
objects are expected to
also implement the events::EventTarget
interface so
that event listeners can be registered on asynchronous
DOMBuilder
objects.
Events supported by asynchronous DOMBuilder
are:
LSLoadEvent
LSProgressEvent
Note: All events defined in this specification use the
namespace URI "http://www.w3.org/2002/DOMLS"
.
DOMBuilder
s have a number of named features that
can be queried or set. The name of DOMBuilder
features
must be valid XML names. Implementation specific features
(extensions) should choose a implementation specific prefix to
avoid name collisions.
Even if all features must be recognized by all implementations,
being able to set a state (true
or false
)
is not always required. The following list of recognized features
indicates the definitions of each feature state, if setting the
state to true
or false
must be supported
or is optional and, which state is the default one:
"canonical-form"
Document.setNormalizationFeature
in [DOM Level 3
Core]."cdata-sections"
Document.setNormalizationFeature
in [DOM Level 3
Core]."certified"
"charset-overrides-xml-encoding"
true
DOMInputSource
overrides encodings from the protocol.false
"comments"
Document.setNormalizationFeature
in [DOM Level 3
Core]."datatype-normalization"
Document.setNormalizationFeature
in [DOM Level 3
Core]."entities"
Document.setNormalizationFeature
in [DOM Level 3
Core]."infoset"
Document.setNormalizationFeature
in [DOM Level 3
Core]. Setting this feature to true
will also
force the feature namespaces
to
true
."namespaces"
true
false
"namespace-declarations"
Document.setNormalizationFeature
in [DOM Level 3
Core]."supported-mediatypes-only"
true
false
"unknown-characters"
true
false
"validate"
Document.setNormalizationFeature
in [DOM Level 3
Core]."validate-if-schema"
Document.setNormalizationFeature
in [DOM Level 3
Core]."whitespace-in-element-content"
Document.setNormalizationFeature
in [DOM Level 3
Core].interface DOMBuilder { attribute DOMEntityResolver entityResolver; attribute DOMErrorHandler errorHandler; attribute DOMBuilderFilter filter; void setFeature(in DOMString name, in boolean state) raises(DOMException); boolean canSetFeature(in DOMString name, in boolean state); boolean getFeature(in DOMString name) raises(DOMException); Document parseURI(in DOMString uri); Document parse(in DOMInputSource is); // ACTION_TYPES const unsigned short ACTION_REPLACE = 1; const unsigned short ACTION_APPEND_AS_CHILDREN = 2; const unsigned short ACTION_INSERT_AFTER = 3; const unsigned short ACTION_INSERT_BEFORE = 4; void parseWithContext(in DOMInputSource is, in Node cnode, in unsigned short action) raises(DOMException); };
A set of possible actions for the parseWithContext
method.
ACTION_APPEND_AS_CHILDREN
Element
or a DocumentFragment
.ACTION_INSERT_AFTER
Element
.ACTION_INSERT_BEFORE
Element
.ACTION_REPLACE
Element
,
Text
, CDATASection
, Comment
,
ProcessingInstruction
, or EntityReference
node.entityResolver
of type DOMEntityResolver
DOMEntityResolver
has been specified, each time a reference to an external entity is
encountered the DOMBuilder
will pass the public and
system IDs to the entity resolver, which can then specify the
actual source of the entity.null
, the resolution of entities
in the document is implementation dependent.errorHandler
of type
DOMErrorHandler
DOMDocumentBuilder
will call back to
the errorHandler
with the error information. When the
document loading process calls the error handler the node closest
to where the error occured is passed to the error handler, if the
implementation is unable to pass the node where the error occures
the document Node is passed to the error handler. In addition to
passing the Node closest to to where the error occured, the
implementation should also pass any other valuable information to
the error handler, such as file name, line number, and so on.
Mutations to the document from within an error handler will result
in implementation dependent behaviour.filter
of type DOMBuilderFilter
Element
node. The filter implementation can choose to
remove the element from the document being constructed (unless the
element is the document element) or to terminate the parse early.
If the document is being validated when it's loaded the validation
happens before the filter is called.canSetFeature
name
of type
DOMString
state
of type
boolean
true
or
false
).
|
|
getFeature
name
of type
DOMString
|
The current state of the feature ( |
|
NOT_FOUND_ERR: Raised when the |
parse
DOMInputSource
.
is
of type DOMInputSource
DOMInputSource
from which the source document is to be read.
|
If the |
parseURI
uri
of type
DOMString
|
If the |
parseWithContext
DOMInputSource
and insert the content into an existing document at the position
specified with the contextNode
and action
arguments. When parsing the input stream the context node is used
for resolving unbound namespace prefixes. The Document
node, attached to the context node, is used to resolved default
attributes and entity references.is
of type DOMInputSource
DOMInputSource
from which the source document is to be read. The source document
must be an XML fragment, i.e. anything except an XML Document, a
DOCTYPE, entities declarations, notations declarations, or XML or
text declarations.cnode
of type
Node
Document
node, a
DocumentFragment
node, or a node of a type that is
allowed as a child of an element, e.g. it can not be an attribute
node.action
of type
unsigned short
|
NOT_SUPPORTED_ERR: Raised when the NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is readonly. |
setFeature
DOMBuilder
to recognize a feature
name but to be unable to set its value.
name
of type
DOMString
state
of type
boolean
true
or
false
).
|
NOT_SUPPORTED_ERR: Raised when the NOT_FOUND_ERR: Raised when the |
A DOM application may use the hasFeature(feature,
version)
method of the DOMImplementation
interface with parameter values "LS-Save" and "3.0" (respectively)
to determine whether or not these interfaces are supported by the
implementation. In order to fully support them, an implementation
must also support the "Core" feature defined in the DOM Level 3
Core specification [DOM Level 3 Core]. Please, refer to
additional information about
conformance in the DOM Level 3 Core specification [DOM Level 3
Core].
DOMWriter
provides an API for serializing (writing)
a DOM document out in an XML document. The XML data is written to
an output stream, the type of which depends on the specific
language bindings in use.
During serialization of XML data, namespace fixup is done when
possible as defined in [DOM Level 3 Core], Appendix B. [DOM Level
2 Core] allows empty strings as a real namespace URI. If the
namespaceURI
of a Node
is empty string,
the serialization will treat them as null
, ignoring
the prefix if any.
Note: should the remark on DOM Level 2 namespace URI included in the namespace algorithm in Core instead?
DOMWriter
accepts any node type for serialization.
For nodes of type Document
or Entity
,
well formed XML will be created if possible. The serialized output
for these node types is either as a Document or an External Entity,
respectively, and is acceptable input for an XML parser. For all
other types of nodes the serialized form is not specified, but
should be something useful to a human for debugging or diagnostic
purposes. Note: rigorously designing an external (source) form for
stand-alone node types that don't already have one defined in [XML 1.0]
seems a bit much to take on here.
Within a Document, DocumentFragment, or Entity being serialized, Nodes are processed as follows
writeNode
defined in the DOMWriter
interface, output the entity
expansion but no namespace fixup is done. The resulting output will
be valid as an external entity.&entityName;
" in the output. Child nodes
(the expansion) of the entity reference are ignored.true
, CDATA sections are split, and
the unrepresentable characters are serialized as numeric character
references in ordinary content. The exact position and number of
splits is not specified.false
, unrepresentable characters
in a CDATA section are reported as errors. The error is not
recoverable - there is no mechanism for supplying alternative
characters and continuing with the serialization.Note: The serialization of a DOM Node does not always
generate a well-formed XML
document, i.e. a DOMBuilder
might
through fatal errors when parsing the resulting serialization.
Within the character data of a document (outside of markup), any characters that cannot be represented directly are replaced with character references. Occurrences of '<' and '&' are replaced by the predefined entities < and &. The other predefined entities (>, &apos, etc.) are not used; these characters can be included directly. Any character that can not be represented directly in the output character encoding is serialized as a numeric character reference.
Attributes not containing quotes are serialized in quotes. Attributes containing quotes but no apostrophes are serialized in apostrophes (single quotes). Attributes containing both forms of quotes are serialized in quotes, with quotes within the value represented by the predefined entity ". Any character that can not be represented directly in the output character encoding is serialized as a numeric character reference.
Within markup, but outside of attributes, any occurrence of a character that cannot be represented in the output character encoding is reported as an error. An example would be serializing the element <LaCañada/> with the encoding="us-ascii".
When requested by setting the normalize-characters
feature on DOMWriter
, all data to be serialized, both
markup and character data, is W3C Text normalized according to the
rules defined in [CharModel]. The W3C Text
normalization process affects only the data as it is being written;
it does not alter the DOM's view of the document after
serialization has completed.
Namespaces are fixed up during serialization, the serialization process will verify that namespace declarations, namespace prefixes and the namespace URIs associated with Elements and Attributes are consistent. If inconsistencies are found, the serialized form of the document will be altered to remove them. The algorithm used for doing the namespace fixup while serializing a document is a combination of the algorithms used for lookupNamespaceURI and lookupNamespacePrefix .
Any changes made affect only the namespace prefixes and declarations appearing in the serialized data. The DOM's view of the document is not altered by the serialization operation, and does not reflect any changes made to namespace declarations or prefixes in the serialized output.
While serializing a document the serializer will write out
non-specified values (such as attributes whose
specified
is false
) if the
discard-default-content
feature is set to
true
. If the discard-default-content
flag
is set to false
and a schema is used for validation,
the schema will be also used to determine if a value is specified
or not. If no schema is used, the specified
flag on
attribute nodes is used to determine if attribute values should be
written out.
Ref to Core spec (1.1.9, XML namespaces, 5th paragraph) entity
ref description about warning about unbound entity refs. Entity
refs are always serialized as &foo;
, also mention
this in the load part of this spec.
DOMWriter
s have a number of named features that can
be queried or set. The name of DOMWriter
features must
be valid XML names. Implementation specific features (extensions)
should choose an implementation dependent prefix to avoid name
collisions.
Here is a list of features that must be recognized by all implementations.
Note: Using these features does affect the
Node
being serialized, only its serialized form is
affected.
"discard-default-content"
Document.setNormalizationFeature
in [DOM Level 3
Core]."canonical-form"
true
"format-pretty-print"
to
false.false
"entities"
Document.setNormalizationFeature
in [DOM Level 3
Core]."format-pretty-print"
true
false
"namespaces"
Document.setNormalizationFeature
in [DOM Level 3
Core]."normalize-characters"
Document.setNormalizationFeature
in [DOM Level 3
Core]. Unlike in the Core, the default value for this feature
is true
."split-cdata-sections"
Document.setNormalizationFeature
in [DOM Level 3
Core]."validate"
Document.setNormalizationFeature
in [DOM Level 3
Core]."unknown-characters"
true
false
"whitespace-in-element-content"
Document.setNormalizationFeature
in [DOM Level 3
Core].interface DOMWriter { void setFeature(in DOMString name, in boolean state) raises(DOMException); boolean canSetFeature(in DOMString name, in boolean state); boolean getFeature(in DOMString name) raises(DOMException); attribute DOMString encoding; attribute DOMString newLine; attribute DOMWriterFilter filter; attribute DOMErrorHandler errorHandler; boolean writeNode(in DOMOutputStream destination, in Node wnode); DOMString writeToString(in Node wnode) raises(DOMException); };
encoding
of type
DOMString
null
or empty, but
the item to be written, or the owner document of the item,
specifies an encoding (i.e. the "actualEncoding" from the document)
specified encoding, that value will be used.null
.errorHandler
of type
DOMErrorHandler
filter
of type DOMWriterFilter
newLine
of type
DOMString
null
null
.canSetFeature
name
of type
DOMString
state
of type
boolean
true
or
false
).
|
|
getFeature
name
of type
DOMString
|
The current state of the feature ( |
|
NOT_FOUND_ERR: Raised when the |
setFeature
DOMWriter
to recognize a feature
name but to be unable to set its value.
name
of type
DOMString
state
of type
boolean
true
or
false
).
|
NOT_SUPPORTED_ERR: Raised when the Raise a NOT_FOUND_ERR When the |
writeNode
DOMWriter
. Writing a Document or
Entity node produces a serialized form that is well formed XML,
when possible (Entity nodes might not always be well formed XML in
themselves). Writing other node types produces a fragment of text
in a form that is not fully defined by this document, but that
should be useful to a human for debugging or diagnostic
purposes.destination
of type DOMOutputStream
wnode
of type
Node
Document
or Entity
node to be
written. For other node types, something sensible should be
written, but the exact serialized form is not specified.
|
Returns |
writeToString
DOMWriter
. The result of
serializing the node is returned as a DOMString (this method
completely ignores all the encoding information available). Writing
a Document or Entity node produces a serialized form that is well
formed XML. Writing other node types produces a fragment of text in
a form that is not fully defined by this document, but that should
be useful to a human for debugging or diagnostic purposes.wnode
of type
Node
|
Returns the serialized data, or |
|
DOMSTRING_SIZE_ERR: Raised if the resulting string is too long
to fit in a |
DOMWriterFilter
s provide applications the ability
to examine nodes as they are being serialized.
DOMWriterFilter
lets the application decide what nodes
should be serialized or not.
The Document
, DocumentType
,
Notation
, and Entity
nodes are not passed
to the filter.
interface DOMWriterFilter : traversal::NodeFilter { readonly attribute unsigned long whatToShow; };
whatToShow
of type
unsigned long
, readonlyDOMWriter
what types
of nodes to show to the filter. See NodeFilter
for
definition of the constants. The constants
SHOW_ATTRIBUTE
, SHOW_DOCUMENT
,
SHOW_DOCUMENT_TYPE
, SHOW_NOTATION
, and
SHOW_DOCUMENT_FRAGMENT
are meaningless here, those
nodes will never be passed to a DOMWriterFilter
.
Entity
nodes are not passed to the filter.DOMSystemException
needs to
be defined as part of the error handling module that is to be
shared with AS. Common I/O type errors need to be defined for it,
so that they can be reported in a uniform way. A way to embed
errors or exceptions from the OS or language environment is needed,
to provide full information to applications that want it.DocumentBuilder
(Sun) and DOMParser
(Xerces).SAXException.toString
and
SAXException.getMessage
always the same? If not, we
need to add another attribute.true
.DOMASBuilder
interface in
the AS specDOMASBuilder
interface in
the AS specfalse
. Does this mean
that the default depends on the parser, or that some sort of an
error happens if a parse is attempted before resetting the
property, or what?false
.false
? Discussed at f2f. I'm not so sure now. Some of
the properties have somewhat non-standard behavior when
false
- leaving out ER nodes or whitespace, for
example - and support of false
will probably not even
be required.false
. But validation should.true
. Illegal for it to be false
and
createEntityReferenceNodes to be true
.
supported-mediatypes-only
feature on DOMBuilder
.true
during serialization that these changes
are discarded during serialization.false
then the attribute must be a level 1 node in which case this
information can safely be used.
Attr.specified
discussion.)SKIP
an element in
DOMBuilderFilter::acceptNode
?namespaceURI
in core can be empty string, how
should that be dealt with in DOM LS?namespaceURI
of a Node
is empty string, the serialization will
treat them as null
, ignoring the prefix if any.FILTER_INTERRUPT
if you want to
stop the processing of the document. Interrupting the processing of
the document does no longer guarantee that the entire is XML
well-formed.<foo/><bar/>
foobar
<?xml version="1.0"?> <!DOCTYPE foo> foo and foobar
This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Model Abstract Schemas and Load and Save definitions.
The IDL files are also available as: http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725/idl.zip
// File: ls.idl #ifndef _LS_IDL_ #define _LS_IDL_ #include "dom.idl" #include "events.idl" #include "traversal.idl" #pragma prefix "dom.w3c.org" module ls { typedef Object DOMInputStream; typedef Object DOMOutputStream; typedef Object DOMReader; typedef dom::DOMString DOMString; typedef dom::Node Node; typedef dom::Element Element; typedef dom::DOMErrorHandler DOMErrorHandler; typedef dom::Document Document; interface DOMBuilder; interface DOMWriter; interface DOMInputSource; interface DOMWriterFilter; interface DOMImplementationLS { // DOMIMplementationLSMode const unsigned short MODE_SYNCHRONOUS = 1; const unsigned short MODE_ASYNCHRONOUS = 2; DOMBuilder createDOMBuilder(in unsigned short mode, in DOMString schemaType) raises(dom::DOMException); DOMWriter createDOMWriter(); DOMInputSource createDOMInputSource(); }; interface DocumentLS { attribute boolean async; // raises(dom::DOMException) on setting void abort(); boolean load(in DOMString uri); boolean loadXML(in DOMString source); DOMString saveXML(in Node snode) raises(dom::DOMException); }; interface DOMInputSource { attribute DOMInputStream byteStream; attribute DOMReader characterStream; attribute DOMString stringData; attribute DOMString encoding; attribute DOMString publicId; attribute DOMString systemId; attribute DOMString baseURI; }; interface DOMEntityResolver { DOMInputSource resolveEntity(in DOMString publicId, in DOMString systemId, in DOMString baseURI); }; interface DOMBuilderFilter { // Constants returned by startElement and acceptNode const short FILTER_ACCEPT = 1; const short FILTER_REJECT = 2; const short FILTER_SKIP = 3; const short FILTER_INTERRUPT = 4; unsigned short startElement(in Element elt); unsigned short acceptNode(in Node enode); readonly attribute unsigned long whatToShow; }; interface DOMBuilder { attribute DOMEntityResolver entityResolver; attribute DOMErrorHandler errorHandler; attribute DOMBuilderFilter filter; void setFeature(in DOMString name, in boolean state) raises(dom::DOMException); boolean canSetFeature(in DOMString name, in boolean state); boolean getFeature(in DOMString name) raises(dom::DOMException); Document parseURI(in DOMString uri); Document parse(in DOMInputSource is); // ACTION_TYPES const unsigned short ACTION_REPLACE = 1; const unsigned short ACTION_APPEND_AS_CHILDREN = 2; const unsigned short ACTION_INSERT_AFTER = 3; const unsigned short ACTION_INSERT_BEFORE = 4; void parseWithContext(in DOMInputSource is, in Node cnode, in unsigned short action) raises(dom::DOMException); }; interface DOMWriter { void setFeature(in DOMString name, in boolean state) raises(dom::DOMException); boolean canSetFeature(in DOMString name, in boolean state); boolean getFeature(in DOMString name) raises(dom::DOMException); attribute DOMString encoding; attribute DOMString newLine; attribute DOMWriterFilter filter; attribute DOMErrorHandler errorHandler; boolean writeNode(in DOMOutputStream destination, in Node wnode); DOMString writeToString(in Node wnode) raises(dom::DOMException); }; interface LSLoadEvent : events::Event { readonly attribute Document newDocument; readonly attribute DOMInputSource inputSource; }; interface LSProgressEvent : events::Event { readonly attribute DOMInputSource inputSource; readonly attribute unsigned long position; readonly attribute unsigned long totalSize; }; interface DOMWriterFilter : traversal::NodeFilter { readonly attribute unsigned long whatToShow; }; }; #endif // _LS_IDL_
This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model Load and Save.
The Java files are also available as http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725/java-binding.zip
package org.w3c.dom.ls; import org.w3c.dom.DOMException; public interface DOMImplementationLS { // DOMIMplementationLSMode public static final short MODE_SYNCHRONOUS = 1; public static final short MODE_ASYNCHRONOUS = 2; public DOMBuilder createDOMBuilder(short mode, String schemaType) throws DOMException; public DOMWriter createDOMWriter(); public DOMInputSource createDOMInputSource(); }
package org.w3c.dom.ls; import org.w3c.dom.Node; import org.w3c.dom.DOMException; public interface DocumentLS { public boolean getAsync(); public void setAsync(boolean async) throws DOMException; public void abort(); public boolean load(String uri); public boolean loadXML(String source); public String saveXML(Node snode) throws DOMException; }
package org.w3c.dom.ls; public interface DOMInputSource { public java.io.InputStream getByteStream(); public void setByteStream(java.io.InputStream byteStream); public java.io.Reader getCharacterStream(); public void setCharacterStream(java.io.Reader characterStream); public String getStringData(); public void setStringData(String stringData); public String getEncoding(); public void setEncoding(String encoding); public String getPublicId(); public void setPublicId(String publicId); public String getSystemId(); public void setSystemId(String systemId); public String getBaseURI(); public void setBaseURI(String baseURI); }
package org.w3c.dom.ls; import org.w3c.dom.Document; import org.w3c.dom.events.Event; public interface LSLoadEvent extends Event { public Document getNewDocument(); public DOMInputSource getInputSource(); }
package org.w3c.dom.ls; import org.w3c.dom.events.Event; public interface LSProgressEvent extends Event { public DOMInputSource getInputSource(); public int getPosition(); public int getTotalSize(); }
package org.w3c.dom.ls; public interface DOMEntityResolver { public DOMInputSource resolveEntity(String publicId, String systemId, String baseURI); }
package org.w3c.dom.ls; import org.w3c.dom.Element; import org.w3c.dom.Node; public interface DOMBuilderFilter { // Constants returned by startElement and acceptNode public static final short FILTER_ACCEPT = 1; public static final short FILTER_REJECT = 2; public static final short FILTER_SKIP = 3; public static final short FILTER_INTERRUPT = 4; public short startElement(Element elt); public short acceptNode(Node enode); public int getWhatToShow(); }
package org.w3c.dom.ls; import org.w3c.dom.Document; import org.w3c.dom.Node; import org.w3c.dom.DOMException; import org.w3c.dom.DOMErrorHandler; public interface DOMBuilder { public DOMEntityResolver getEntityResolver(); public void setEntityResolver(DOMEntityResolver entityResolver); public DOMErrorHandler getErrorHandler(); public void setErrorHandler(DOMErrorHandler errorHandler); public DOMBuilderFilter getFilter(); public void setFilter(DOMBuilderFilter filter); public void setFeature(String name, boolean state) throws DOMException; public boolean canSetFeature(String name, boolean state); public boolean getFeature(String name) throws DOMException; public Document parseURI(String uri); public Document parse(DOMInputSource is); // ACTION_TYPES public static final short ACTION_REPLACE = 1; public static final short ACTION_APPEND_AS_CHILDREN = 2; public static final short ACTION_INSERT_AFTER = 3; public static final short ACTION_INSERT_BEFORE = 4; public void parseWithContext(DOMInputSource is, Node cnode, short action) throws DOMException; }
package org.w3c.dom.ls; import org.w3c.dom.Node; import org.w3c.dom.DOMException; import org.w3c.dom.DOMErrorHandler; public interface DOMWriter { public void setFeature(String name, boolean state) throws DOMException; public boolean canSetFeature(String name, boolean state); public boolean getFeature(String name) throws DOMException; public String getEncoding(); public void setEncoding(String encoding); public String getNewLine(); public void setNewLine(String newLine); public DOMWriterFilter getFilter(); public void setFilter(DOMWriterFilter filter); public DOMErrorHandler getErrorHandler(); public void setErrorHandler(DOMErrorHandler errorHandler); public boolean writeNode(java.io.OutputStream destination, Node wnode); public String writeToString(Node wnode) throws DOMException; }
package org.w3c.dom.ls; import org.w3c.dom.traversal.NodeFilter; public interface DOMWriterFilter extends NodeFilter { public int getWhatToShow(); }
This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model Load and Save definitions.
Many people contributed to the DOM specifications (Level 1, 2 or 3), including members of the DOM Working Group and the DOM Interest Group. We especially thank the following:
Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C team contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).
Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).
This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.
Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.
After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.
Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.
Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.
DOMString
. This indicates that
indexing on a DOMString
occurs in units of 16 bits.
This must not be misunderstood to mean that a
DOMString
can store arbitrary 16-bit units. A
DOMString
is a character string encoded in UTF-16;
this means that the restrictions of UTF-16 as well as the other
relevant restrictions on character strings must be maintained. A
single character, for example in the form of a numeric character
reference, may correspond to one or two 16-bit units.Document
.
This element node is a child of the Document
node. See
Well-Formed
XML Documents in XML [XML 1.0].For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.