#[1]copyright [2]glossary [3]Start [4]author [5]help
[1] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/copyright-notice.html
[2] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/glossary.html
[3] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/Overview.html
[4] mailto:www-dom@w3.org
[5] http://www.w3.org/DOM/
[6]W3C
[6] http://www.w3.org/
Document Object Model (DOM) Level 3 Load and Save Specification
Version 1.0
W3C Candidate Recommendation 07 November 2003
This version:
[7]http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107
[7] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107
Latest version:
[8]http://www.w3.org/TR/DOM-Level-3-LS
[8] http://www.w3.org/TR/DOM-Level-3-LS
Previous version:
[9]http://www.w3.org/TR/2003/WD-DOM-Level-3-LS-20030619
[9] http://www.w3.org/TR/2003/WD-DOM-Level-3-LS-20030619
Editors:
Johnny Stenback, Netscape
Andy Heninger, IBM (until March 2001)
This document is also available in these non-normative formats:
[10]XML file, [11]plain text, [12]PostScript file, [13]PDF file,
[14]single HTML file, and [15]ZIP file.
[10] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/xml-source.xml
[11] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/DOM3-LS.txt
[12] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/DOM3-LS.ps
[13] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/DOM3-LS.pdf
[14] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/DOM3-LS.html
[15] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/DOM3-LS.zip
[16]Copyright ©2003 [17]W3C^® ([18]MIT, [19]ERCIM, [20]Keio), All
Rights Reserved. W3C [21]liability, [22]trademark, [23]document use
and [24]software licensing rules apply.
[16] http://www.w3.org/Consortium/Legal/ipr-notice#Copyright
[17] http://www.w3.org/
[18] http://www.lcs.mit.edu/
[19] http://www.ercim.org/
[20] http://www.keio.ac.jp/
[21] http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer
[22] http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks
[23] http://www.w3.org/Consortium/Legal/copyright-documents
[24] http://www.w3.org/Consortium/Legal/copyright-software
_________________________________________________________________
Abstract
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 load the content of an XML
document into a DOM document and serialize a DOM document into an XML
document; DOM documents being defined in [25]DOM Level 2 Core] or
newer, and XML documents being defined in [26]XML 1.0] or newer.
Status of this document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical
report can be found in the [27]W3C technical reports index at
http://www.w3.org/TR/.
[27] http://www.w3.org/TR/
This document contains the Document Object Model Level 3 Load and Save
specification and is a [28]Candidate Recommendation Working Draft for
review by W3C members and other interested parties. It is based on the
feedback during the [29]Last Call period and the feedback received on
the DOM Level 3 Core specification. The DOM Working Group expects to
request that the Director advance this specification to Proposed
Recommendation after the DOM Working Group documents two interoperable
implementations of at least one normative binding. Basic tests of
functionalities provided in this specification will be produced and
used in this effort. The two implementations must be produced by
different organizations. Implementation feedbacks are welcome until 30
November 2003 and have to be sent to the public mailing list
[30]www-dom@w3.org ([31]public archive).
[28] http://www.w3.org/2003/06/Process-20030618/tr.html#RecsCR
[29] http://www.w3.org/2003/06/19-dom-ls-issues/issues.html
[30] mailto:www-dom@w3.org
[31] http://lists.w3.org/Archives/Public/www-dom/
Individuals or organizations are also invited to send a message to the
public mailing list if they intend to produce an implementation of
this module. The [32]implementation report is available.
[32] http://www.w3.org/2003/10/DOM-Level-3-LS-implementations.html
Given the lack of implementation commitments regarding character
normalization, the DOM Working Group considers it "at risk". This
affects the "check-character-normalization" and "normalize-characters"
parameters defined in the DOMConfiguration interface in the [33]DOM
Level 3 Core]. The Working Group may remove the parameters before
requesting Proposed Recommendation status.
Publication as a Candidate Recommendation does not imply endorsement
by the W3C Membership. This is a draft document and may be updated,
replaced or obsoleted by other documents at any time. It is
inappropriate to cite this document as other than work in progress.
This document has been produced as part of the [34]W3C DOM Activity.
The authors of this document are the DOM Working Group members.
[34] http://www.w3.org/DOM/Activity.html
Patent disclosures relevant to this specification may be found on the
Working Group's [35]patent disclosure page.
[35] http://www.w3.org/2002/08/02-DOM-Disclosures.html
Table of contents
* [36]Expanded Table of Contents
* [37]W3C Copyright Notices and Licenses
* [38]1. Document Object Model Load and Save
* [39]Appendix A: IDL Definitions
* [40]Appendix B: Java Language Binding
* [41]Appendix C: ECMAScript Language Binding
* [42]Appendix D: Acknowledgements
* [43]Glossary
* [44]References
* [45]Index
07 November 2003
Expanded Table of Contents
* [46]Expanded Table of Contents
* [47]W3C Copyright Notices and Licenses
+ [48]W3C^® Document Copyright Notice and License
+ [49]W3C^® Software Copyright Notice and License
+ [50]W3C^® Short Software Notice
* [51]1 Document Object Model Load and Save
+ [52]1.1 Overview of the Interfaces
+ [53]1.2 Basic types
o [54]1.2.1 The LSInputStream type
o [55]1.2.2 The LSOutputStream type
o [56]1.2.3 The LSReader type
o [57]1.2.4 The LSWriter type
+ [58]1.3 Fundamental interfaces
* [59]Appendix A: IDL Definitions
* [60]Appendix B: Java Language Binding
* [61]Appendix C: ECMAScript Language Binding
* [62]Appendix D: Acknowledgements
+ [63]D.1 Production Systems
* [64]Glossary
* [65]References
+ [66]1 Normative references
+ [67]2 Informative references
* [68]Index
07 November 2003
W3C Copyright Notices and Licenses
Copyright © 2003 [69]World Wide Web Consortium, ([70]Massachusetts
Institute of Technology, [71]European Research Consortium for
Informatics and Mathematics, [72]Keio University). All Rights
Reserved.
[69] http://www.w3.org/
[70] http://www.lcs.mit.edu/
[71] http://www.ercim.org/
[72] http://www.keio.ac.jp/
This document is published under the [73]W3C^® Document Copyright
Notice and License. The bindings within this document are published
under the [74]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.
_________________________________________________________________
W3C^® Document Copyright Notice and License
Note: This section is a copy of the W3C^® Document Notice and License
and could be found at
[75]http://www.w3.org/Consortium/Legal/2002/copyright-documents-200212
31.
[75] http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
Copyright © 2003 [76]World Wide Web Consortium, ([77]Massachusetts
Institute of Technology, [78]European Research Consortium for
Informatics and Mathematics, [79]Keio University). All Rights
Reserved.
[76] http://www.w3.org/
[77] http://www.lcs.mit.edu/
[78] http://www.ercim.org/
[79] http://www.keio.ac.jp/
http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
Public documents on the W3C site are provided by the copyright holders
under the following license. 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 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:
1. A link or URL to the original W3C document.
2. The pre-existing copyright notice of the original author, or if it
doesn't exist, a notice (hypertext is preferred, but a textual
representation is permitted) of the form: "Copyright ©
[$date-of-document] [80]World Wide Web Consortium,
([81]Massachusetts Institute of Technology, [82]European Research
Consortium for Informatics and Mathematics, [83]Keio University).
All Rights Reserved.
[84]http://www.w3.org/Consortium/Legal/2002/copyright-documents-20
021231"
3. If it exists, the STATUS of the W3C document.
[80] http://www.w3.org/
[81] http://www.lcs.mit.edu/
[82] http://www.ercim.org/
[83] http://www.keio.ac.jp/
[84] http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
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 [85]Copyright FAQ) are satisfied, the right to
create modifications or derivatives is sometimes granted by the W3C to
individuals complying with those requirements.
[85] http://www.w3.org/Consortium/Legal/IPR-FAQ
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.
_________________________________________________________________
W3C^® Software Copyright Notice and License
Note: This section is a copy of the W3C^® Software Copyright Notice
and License and could be found at
[86]http://www.w3.org/Consortium/Legal/2002/copyright-software-2002123
1
[86] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
Copyright © 2003 [87]World Wide Web Consortium, ([88]Massachusetts
Institute of Technology, [89]European Research Consortium for
Informatics and Mathematics, [90]Keio University). All Rights
Reserved.
[87] http://www.w3.org/
[88] http://www.lcs.mit.edu/
[89] http://www.ercim.org/
[90] http://www.keio.ac.jp/
http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
This work (and included software, documentation such as READMEs, 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 copy, modify, and distribute 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:
1. The full text of this NOTICE in a location viewable to users of
the redistributed or derivative work.
2. Any pre-existing intellectual property disclaimers, notices, or
terms and conditions. If none exist, the [91]W3C^® Short Software
Notice should be included (hypertext is preferred, text is
permitted) within the body of any redistributed or derivative
code.
3. Notice of any changes or modifications to the files, including the
date changes were made. (We recommend you provide URIs to the
location from which the code is derived.)
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.
W3C^® Short Software Notice
Note: This section is a copy of the W3C^® Short Software Notice and
could be found at
[92]http://www.w3.org/Consortium/Legal/2002/copyright-software-short-n
otice-20021231
[92] http://www.w3.org/Consortium/Legal/2002/copyright-software-short-notice-20021231
Copyright © 2003 [93]World Wide Web Consortium, ([94]Massachusetts
Institute of Technology, [95]European Research Consortium for
Informatics and Mathematics, [96]Keio University). All Rights
Reserved.
[93] http://www.w3.org/
[94] http://www.lcs.mit.edu/
[95] http://www.ercim.org/
[96] http://www.keio.ac.jp/
Copyright © [$date-of-software] [97]World Wide Web Consortium,
([98]Massachusetts Institute of Technology, [99]European Research
Consortium for Informatics and Mathematics, [100]Keio University). All
Rights Reserved. This work is distributed under the W3C^® Software
License [$1\47] in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.
[97] http://www.w3.org/
[98] http://www.lcs.mit.edu/
[99] http://www.ercim.org/
[100] http://www.keio.ac.jp/
[$1\47]
http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
07 November 2003
1. Document Object Model Load and Save
Editors:
Johnny Stenback, Netscape
Andy Heninger, IBM (until March 2001)
Table of contents
* [101]1.1 Overview of the Interfaces
* [102]1.2 Basic types
+ [103]1.2.1 The LSInputStream type
o [104]LSInputStream
+ [105]1.2.2 The LSOutputStream type
o [106]LSOutputStream
+ [107]1.2.3 The LSReader type
o [108]LSReader
+ [109]1.2.4 The LSWriter type
o [110]LSWriter
* [111]1.3 Fundamental interfaces
+ [112]DOMImplementationLS, [113]LSParser, [114]LSInput,
[115]LSResourceResolver, [116]LSParserFilter,
[117]LSProgressEvent, [118]LSLoadEvent, [119]LSSerializer,
[120]LSOutput, [121]LSSerializerFilter
This section defines a set of interfaces for loading and saving
document objects as defined in [122]DOM Level 2 Core] or newer. 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 [123]API also allows filtering of XML
content using only DOM API calls; access and manipulation of the
Document is defined in [124]DOM Level 2 Core] or newer.
The proposal for loading is influenced by the Java APIs for XML
Processing [125]JAXP] and by SAX2 [126]SAX].
1.1 Overview of the Interfaces
The list of interfaces involved with the Loading and Saving XML
documents is:
* [127]DOMImplementationLS -- An extended DOMImplementation
interface that provides the factory methods for creating the
objects required for loading and saving.
* [128]LSParser -- An interface for parsing data into DOM documents.
* [129]LSInput -- Encapsulates information about the data to be
loaded.
* [130]LSResourceResolver -- Provides a way for applications to
redirect references to external resources when parsing.
* [131]LSParserFilter -- Provides the ability to examine and
optionally remove nodes as they are being processed while parsing.
* [132]LSSerializer -- An interface for serializing DOM documents or
nodes.
* [133]LSOutput -- Encapsulates information about the destination
for the data to be output.
* [134]LSSerializerFilter -- Provides the ability to examine and
optionally remove nodes as they are being processed while
serializing DOM nodes.
1.2 Basic types
To ensure interoperability, this specification specifies the following
basic types used in various DOM modules. Even though the DOM uses the
basic types in the interfaces, bindings may use different types and
normative bindings are only given for Java and ECMAScript in this
specification.
1.2.1 The [135]LSInputStream type
This type is used to represent a sequence of input bytes.
Type Definition LSInputStream
A [136]LSInputStream represents a reference to a byte stream
source of an XML input.
IDL Definition
typedef Object [137]LSInputStream;
Note: For Java, [138]LSInputStream is bound to the java.io.InputStream
type. For ECMAScript, [139]LSInputStream is bound to Object.
1.2.2 The [140]LSOutputStream type
This type is used to represent a sequence of output bytes.
Type Definition LSOutputStream
A [141]LSOutputStream represents a byte stream destination for
the XML output.
IDL Definition
typedef Object [142]LSOutputStream;
Note: For Java, [143]LSOutputStream is bound to the
java.io.OutputStream type. For ECMAScript, [144]LSOutputStream is
bound to Object.
1.2.3 The [145]LSReader type
This type is used to represent a sequence of input characters in
[146]16-bit units. The encoding used for the characters is UTF-16, as
defined in [147]Unicode] and in [148]ISO/IEC 10646]).
Type Definition LSReader
A [149]LSReader represents a character stream for the XML
input.
IDL Definition
typedef Object [150]LSReader;
Note: For Java, [151]LSReader is bound to the java.io.Reader type. For
ECMAScript, [152]LSReader is NOT bound, and therefore as no
recommended meaning in ECMAScript.
1.2.4 The [153]LSWriter type
This type is used to represent a sequence of output characters in
[154]16-bit units. The encoding used for the characters is UTF-16, as
defined in [155]Unicode] and in [156]ISO/IEC 10646]).
Type Definition LSWriter
A [157]LSWriter represents a character stream for the XML
input.
IDL Definition
typedef Object [158]LSWriter;
Note: For Java, [159]LSWriter is bound to the java.io.Writer type. For
ECMAScript, [160]LSWriter is NOT bound, and therefore as no
recommended meaning in ECMAScript.
1.3 Fundamental interfaces
The interface within this section is considered fundamental, and must
be fully implemented by all conforming implementations of the DOM Load
and Save module.
A DOM application may use the hasFeature(feature, version) method of
the DOMImplementation interface with parameter values "LS" (or
"LS-Async") 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 [161]DOM Level 2 Core].
A DOM application may use the hasFeature(feature, version) method of
the DOMImplementation interface with parameter values "LS-Async" and
"3.0" (respectively) to determine whether or not the asynchronous mode
is supported by the implementation. In order to fully support the
asynchronous mode, an implementation must also support the "LS"
feature defined in this section.
For additional information about [162]conformance, please see the DOM
Level 3 Core specification [163]DOM Level 3 Core].
[162] http://www.w3.org/TR/DOM-Level-3-Core/introduction.html#ID-Conformance
Interface DOMImplementationLS
DOMImplementationLS contains the factory methods for creating
Load and Save objects.
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 [164]DOM Level 3 Core], by using the method
DOMImplementation.getFeature with parameter values "LS" (or
"LS-Async") and "3.0" (respectively).
IDL Definition
interface [165]DOMImplementationLS {
// DOMImplementationLSMode
const unsigned short [166]MODE_SYNCHRONOUS = 1;
const unsigned short [167]MODE_ASYNCHRONOUS = 2;
[168]LSParser [169]createLSParser(in unsigned short mode,
in DOMString schemaType)
raises(DOMException);
[170]LSSerializer [171]createLSSerializer();
[172]LSInput [173]createLSInput();
[174]LSOutput [175]createLSOutput();
};
Definition group DOMImplementationLSMode
Integer parser mode constants.
Defined Constants
MODE_ASYNCHRONOUS
Create an asynchronous [176]LSParser.
MODE_SYNCHRONOUS
Create a synchronous [177]LSParser.
Methods
createLSInput
Create a new empty input source object where
[178]LSInput.characterStream,
[179]LSInput.byteStream, [180]LSInput.stringData
[181]LSInput.systemId, [182]LSInput.publicId,
[183]LSInput.baseURI, and [184]LSInput.encoding are
null, and [185]LSInput.certifiedText is false.
Return Value
[186]LSInput
The newly created input object.
No Parameters
No Exceptions
createLSOutput
Create a new empty output destination object where
[187]LSOutput.characterStream,
[188]LSOutput.byteStream, [189]LSOutput.systemId,
[190]LSOutput.encoding are null.
Return Value
[191]LSOutput
The newly created output object.
No Parameters
No Exceptions
createLSParser
Create a new [192]LSParser. The newly constructed
parser may then be configured by means of its
DOMConfiguration object, and used to parse
documents by means of its parse method.
Parameters
mode of type unsigned short
The mode argument is either MODE_SYNCHRONOUS
or MODE_ASYNCHRONOUS, if mode is
MODE_SYNCHRONOUS then the [193]LSParser that
is created will operate in synchronous mode,
if it's MODE_ASYNCHRONOUS then the
[194]LSParser that is created will operate in
asynchronous mode.
schemaType of type DOMString
An absolute URI representing the type of the
[195]schema language used during the load of
a Document using the newly created
[196]LSParser. Note that no lexical checking
is done on the absolute URI. In order to
create a [197]LSParser for any kind of schema
types (i.e. the LSParser will be free to use
any schema found), use the value null.
Note: For W3C XML Schema [198]XML Schema
Part 1], applications must use the value
"http://www.w3.org/2001/XMLSchema". For XML
DTD [199]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.
Return Value
[200]LSParser
The newly created [201]LSParser object. This [202]LSParser is either
synchronous or asynchronous depending on the value of the mode
argument.
Note: By default, the newly created [203]LSParser does not contain a
DOMErrorHandler, i.e. the value of the "[204] error-handler"
configuration parameter is null. However, implementations may provide
a default error handler at creation time. In that case, the initial
value of the "error-handler" configuration parameter on the new
created [205]LSParser contains a reference to the default error
handler.
[204] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler
Exceptions
DOMException
NOT_SUPPORTED_ERR: Raised if the requested mode or schema type is not
supported.
createLSSerializer
Create a new [206]LSSerializer object.
Return Value
[207]LSSerializer
The newly created [208]LSSerializer object.
Note: By default, the newly created [209]LSSerializer has no
DOMErrorHandler, i.e. the value of the "error-handler" configuration
parameter is null. However, implementations may provide a default
error handler at creation time. In that case, the initial value of the
"error-handler" configuration parameter on the new created
[210]LSSerializer contains a reference to the default error handler.
No Parameters
No Exceptions
Interface LSParser
An interface to an object that is able to build, or augment, a
DOM tree from various input sources.
LSParser provides an API for parsing XML and building the
corresponding DOM document structure. A LSParser instance can
be obtained by invoking the
[211]DOMImplementationLS.createLSParser() method.
As specified in [212]DOM Level 3 Core], when a document is
first made available via the LSParser:
+ there will never be two adjacent nodes of type NODE_TEXT, and
there will never be empty text nodes.
+ it is expected that the value and nodeValue attributes of an
Attr node initially return the [213]XML 1.0 normalized value.
However, if the parameters "[214] validate-if-schema" and
"[215] 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 parameters "[216]
datatype-normalization" is set to false, the XML 1.0
attribute normalization is guaranteed to occur, and if the
attributes list does not contain namespace declarations, the
attributes attribute on Element node represents the property
[attributes] defined in [217]XML Information Set].
[213] http://www.w3.org/TR/2000/REC-xml-20001006#AVNormalize
[214] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema
[215] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization
[216] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization
Asynchronous LSParser objects are expected to also implement
the events::EventTarget interface so that event listeners can
be registered on asynchronous LSParser objects.
Events supported by asynchronous LSParser objects are:
load
The LSParser finishes to load the document. See also the
definition of the [218]LSLoadEvent interface.
progress
The LSParser signals progress as data is parsed.
This specification does not attempt to define exactly
when progress events should be dispatched, that is
intentionally left as implementation depenedent, but here
is one example of how an application might dispatch
progress events. Once the parser starts receiving data, a
progress event is dispatched to indicate that the parsing
starts, then from there on, a progress event is
dispatched for every 4096 bytes of data that is received
and processed. This is only one example, though, and
implementations can choose to dispatch progress events at
any time while parsing, or not dispatch them at all.
See also the definition of the [219]LSProgressEvent
interface.
Note: All events defined in this specification use the
namespace URI "http://www.w3.org/2002/DOMLS".
While parsing an input source, errors are reported to the
application through the error handler ([220]LSParser.config's
"[221] error-handler" parameter). This specification does in no
way try to define all possible errors that can occur while
parsing XML, or any other markup, but some common error cases
are defined. The types (DOMError.type) of errors and warnings
defined by this specification are:
[221] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler
"check-character-normalization-failure" [error]
Raised if the paramter "[222]
check-character-normalization" is set to true and a
string is encoutered that fails normalization checking.
[222] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-check-character-normalization
"doctype-not-allowed" [fatal]
Raised if the configuration parameter
"[223]disallow-doctype" is set to true and a doctype is
encountered.
"pi-base-uri-not-preserved" [warning]
Raised if a processing instruction is encoutered in a
location where the base URI of the processing instruction
can not be preserved.
One example of a case where this warning will be raised
is if the configuration parameter "[224] entities" is set
to false and the following XML file is parsed:
[224] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities
&e;
And subdir/myentity.ent contains:
"unbound-prefix-in-entity" [warning]
An implementation dependent warning that may be raised if
the configuration parameter "[225] namespaces" is set to
true and an unbound namespace prefix is encountered in an
entity's replacement text. Raising this warning is not
enforced since some existing parsers may not recognize
unbound namespace prefixes in the replacement text of
entities.
[225] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces
"unknown-character-denormalization" [fatal]
Raised if the configuration parameter
"[226]ignore-unknown-character-denormalizations" is set
to false and a character is encountered for which the
processor cannot determine the normalization properties.
"unsupported-encoding" [fatal]
Raised if an unsupported encoding is encountered.
"unsupported-media-type" [fatal]
Raised if the configuration parameter
"[227]supported-media-types-only" is set to true and an
unsupported media type is encountered.
In addition to raising the defined errors and warnings,
implementations are expected to raise implementation specific
errors and warnings for any other error and warning cases such
as IO errors (file not found, permission denied,...), XML
well-formedness errors, and so on.
IDL Definition
interface [228]LSParser {
readonly attribute DOMConfiguration [229]config;
attribute [230]LSParserFilter [231]filter;
readonly attribute boolean [232]async;
readonly attribute boolean [233]busy;
Document [234]parse(in [235]LSInput input)
raises(DOMException);
Document [236]parseURI(in DOMString uri)
raises(DOMException);
// ACTION_TYPES
const unsigned short [237]ACTION_APPEND_AS_CHILDREN = 1;
const unsigned short [238]ACTION_REPLACE_CHILDREN = 2;
const unsigned short [239]ACTION_INSERT_BEFORE = 3;
const unsigned short [240]ACTION_INSERT_AFTER = 4;
const unsigned short [241]ACTION_REPLACE = 5;
Node [242]parseWithContext(in [243]LSInput input,
in Node contextArg,
in unsigned short action)
raises(DOMException);
void [244]abort();
};
Definition group ACTION_TYPES
A set of possible actions for the parseWithContext
method.
Defined Constants
ACTION_APPEND_AS_CHILDREN
Append the result of the parse operation as
children of the context node. For this action
to work, the context node must be an Element
or a DocumentFragment.
ACTION_INSERT_AFTER
Insert the result of the parse operation as
the immediately following sibling of the
context node. For this action to work the
context node's parent must be an Element or a
DocumentFragment.
ACTION_INSERT_BEFORE
Insert the result of the parse operation as
the immediately preceding sibling of the
context node. For this action to work the
context node's parent must be an Element or a
DocumentFragment.
ACTION_REPLACE
Replace the context node with the result of
the parse operation. For this action to work,
the context node must have a parent, and the
parent must be an Element or a
DocumentFragment.
ACTION_REPLACE_CHILDREN
Replace all the children of the context node
with the result of the parse operation. For
this action to work, the context node must be
an Element, a Document, or a
DocumentFragment.
Attributes
async of type boolean, readonly
true if the LSParser is asynchronous, false if it
is synchronous.
busy of type boolean, readonly
true if the LSParser is currently busy loading a
document, otherwise false.
config of type DOMConfiguration, readonly
The DOMConfiguration object used when parsing an
input source. This DOMConfiguration is specific to
the parse operation and no parameter values from
this DOMConfiguration object are passed
automatically to the DOMConfiguration object on the
Document that is created, or used, by the parse
operation. The DOM application is responsible for
passing any needed parameter values from this
DOMConfiguration object to the DOMConfiguration
object referenced by the Document object.
In addition to the parameters recognized in
[245]DOM Level 3 Core], the DOMConfiguration
objects for LSParser add or modify the following
parameters:
"charset-overrides-xml-encoding"
true
[required] (default)
If a higher level protocol such as HTTP
[246]IETF RFC 2616] provides an
indication of the character encoding of
the input stream being processed, that
will override any encoding specified in
the XML declaration or the Text
declaration (see also section 4.3.3,
"Character Encoding in Entities", in
[247]XML 1.0]). Explicitly setting an
encoding in the [248]LSInput overrides
any encoding from the protocol.
false
[required]
The parser ignores any character set
encoding information from higher-level
protocols.
"disallow-doctype"
true
[optional]
Throw a fatal "doctype-not-allowed"
error if a doctype node is found while
parsing the document. This is useful
when dealing with things like SOAP
envelopes where doctype nodes are not
allowed.
false
[required] (default)
Allow doctype nodes in the document.
"ignore-unknown-character-denormalizations"
true
[required] (default)
If, while verifying full normalization
when [249]XML 1.1] is supported, a
processor encounters characters for
which it cannot determine the
normalization properties, then the
processor will ignore any possible
denormalizations caused by these
characters.
This parameter is ignored for [250]XML
1.0].
false
[optional]
Report an fatal
"unknown-character-denormalization"
error if a character is encountered for
which the processor cannot determine
the normalization properties.
"infoset"
See the definition of DOMConfiguration for a
description of this parameter. Unlike in
[251]DOM Level 3 Core], this parameter will
default to true for LSParser.
"namespaces"
true
[required] (default)
Perform the namespace processing as
defined in [252]XML Namespaces] and
[253]XML Namespaces 1.1].
false
[optional]
Do not perform the namespace
processing.
"resource-resolver"
[required]
A reference to a [254]LSResourceResolver
object, or null. If the value of this
parameter is not null when an external
resource (such as an external XML entity or
an XML schema location) is encountered, the
implementation will request that the
[255]LSResourceResolver referenced in this
parameter resolves the resource.
"supported-media-types-only"
true
[optional]
Check that the media type of the parsed
resource is a supported media type. If
an unsupported media type is
encountered, a fatal error of type
"unsupported-media-type" will be
raised. The media types defined in
[256]IETF RFC 3023] must always be
accepted.
false
[required] (default)
Accept any media type.
The parameter "[257] well-formed" cannot be set to
false.
[257] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-well-formed
filter of type [258]LSParserFilter
When a filter is provided, the implementation will
call out to the filter as it is constructing the
DOM tree structure. The filter can choose to remove
elements from the document being constructed, or to
terminate the parsing early.
The filter is invoked after the operations
requested by the DOMConfiguration parameters have
been applied. For example, if "[259] validate" is
set to true, the validation is done before invoking
the filter.
[259] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate
Methods
abort
Abort the loading of the document that is currently
being loaded by the LSParser. If the LSParser is
currently not busy, a call to this method does
nothing.
No Parameters
No Return Value
No Exceptions
parse
Parse an XML document from a resource identified by
a [260]LSInput.
Parameters
input of type [261]LSInput
The [262]LSInput from which the source of the
document is to be read.
Return Value
Document
If the LSParser is a synchronous LSParser, the newly created and
populated Document is returned. If the LSParser is asynchronous, null
is returned since the document object may not yet be constructed when
this method returns.
Exceptions
DOMException
INVALID_STATE_ERR: Raised if the LSParser's [263]LSParser.busy
attribute is true.
parseURI
Parse an XML document from a location identified by
a URI reference [264]IETF RFC 2396]. If the URI
contains a fragment identifier (see section 4.1 in
[265]IETF RFC 2396]), the behavior is not defined
by this specification, future versions of this
specification may define the behavior.
Parameters
uri of type DOMString
The location of the XML document to be read.
Return Value
Document
If the LSParser is a synchronous LSParser, the newly created and
populated Document is returned. If the LSParser is asynchronous, null
is returned since the document object may not yet be constructed when
this method returns.
Exceptions
DOMException
INVALID_STATE_ERR: Raised if the [266]LSParser.busy attribute is true.
parseWithContext
Parse an XML fragment from a resource identified by
a [267]LSInput and insert the content into an
existing document at the position specified with
the context and action arguments. When parsing the
input stream, the context node (or its parent,
depending on where the result will be inserted) is
used for resolving unbound namespace prefixes. The
context node's ownerDocument node (or the node
itself if the node of type DOCUMENT_NODE) is used
to resolve default attributes and entity
references.
As the new data is inserted into the document, at
least one mutation event is fired per new immediate
child or sibling of the context node.
If the context node is a Document node and the
action is ACTION_REPLACE_CHILDREN, then the
document that is passed as the context node will be
changed such that its xmlEncoding, documentURI,
xmlVersion, actualEncoding, xmlStandalone, and all
other such attributes are set to what they would be
set to if the input source was parsed using
[268]LSParser.parse().
If the LSParser is asynchronous then the insertion
of the resulting DOM structure is atomic, e.g. the
whole structure is inserted only once the whole
input stream is completely parsed without errors.
If an error occurs while parsing, the caller is
notified through the ErrorHandler instance
associated with the "[269] error-handler" parameter
of the DOMConfiguration.
When calling parseWithContext, the values of the
following configuration parameters will be ignored
and their default values will always be used
instead: "[270] validate", "[271]
validate-if-schema", and "[272]
element-content-whitespace". Other parameters will
be treated normally, and the parser is expected to
call the [273]LSParserFilter just as if a whole
document was parsed.
[269] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler
[270] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate
[271] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema
[272] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-element-content-whitespace
Parameters
input of type [274]LSInput
The [275]LSInput from which the source
document is to be read. The source document
must be an XML fragment, i.e. anything except
a complete XML document (except in the case
where the context node of type DOCUMENT_NODE,
and the action is ACTION_REPLACE_CHILDREN), a
DOCTYPE (internal subset), entity
declaration(s), notation declaration(s), or
XML or text declaration(s).
contextArg of type Node
The node that is used as the context for the
data that is being parsed. This node must be
a Document node, a DocumentFragment node, or
a node of a type that is allowed as a child
of an Element node, e.g. it cannot be an
Attribute node.
action of type unsigned short
This parameter describes which action should
be taken between the new set of nodes being
inserted and the existing children of the
context node. The set of possible actions is
defined in ACTION_TYPES above.
Return Value
Node
Return the node that is the result of the parse operation. If the
result is more than one top-level node, the first one is returned.
Exceptions
DOMException
NOT_SUPPORTED_ERR: Raised if the LSParser doesn't support this method.
NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a [276]read
only node.
INVALID_STATE_ERR: Raised if the [277]LSParser.busy attribute is true.
Interface LSInput
This interface represents an input source for data.
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), a base URI, and/or a character
stream.
The exact definitions of a byte stream and a character stream
are binding dependent.
The application is expected to provide objects that implement
this interface whenever such objects are needed. The
application can either provide its own objects that implement
this interface, or it can use the generic factory method
[278]DOMImplementationLS.createLSInput() to create objects that
implement this interface.
The [279]LSParser will use the LSInput object to determine how
to read data. The [280]LSParser will look at the different
inputs specified in the LSInput in the following order to know
which one to read from, the first one that is not null and not
an empty string will be used:
1. [281]LSInput.characterStream
2. [282]LSInput.byteStream
3. [283]LSInput.stringData
4. [284]LSInput.systemId
5. [285]LSInput.publicId
LSInput objects belong to the application. The DOM
implementation will never modify them (though it may make
copies and modify the copies, if necessary).
IDL Definition
interface [286]LSInput {
// Depending on the language binding in use,
// this attribute may not be available.
attribute [287]LSReader [288]characterStream;
attribute [289]LSInputStream [290]byteStream;
attribute DOMString [291]stringData;
attribute DOMString [292]systemId;
attribute DOMString [293]publicId;
attribute DOMString [294]baseURI;
attribute DOMString [295]encoding;
attribute boolean [296]certifiedText;
};
Attributes
baseURI of type DOMString
The base URI to be used (see section 5.1.4 in
[297]IETF RFC 2396]) for resolving a relative
systemId to an absolute URI.
If, when used, the base URI is itself a relative
URI, an empty string, or null, the behavior is
implementation dependent.
byteStream of type [298]LSInputStream
An attribute of a language and binding dependent
type that represents a stream of bytes.
If the application knows the character encoding of
the byte stream, it should set the encoding
attribute. Setting the encoding in this way will
override any encoding specified in an XML
declaration in the data.
certifiedText of type boolean
If set to true, assume that the input is certified
(see section 2.13 in [299]XML 1.1]) when parsing
[300]XML 1.1].
characterStream of type [301]LSReader
Depending on the language binding in use, this
attribute may not be available.
An attribute of a language and binding dependent
type that represents a stream of [302]16-bit units.
The application must encode the stream using UTF-16
(defined in [303]Unicode] and in [304]ISO/IEC
10646]).
encoding of type DOMString
The character encoding, if known. The encoding must
be a string acceptable for an XML encoding
declaration ([305]XML 1.0] section 4.3.3
"Character Encoding in Entities").
This attribute has no effect when the application
provides a character stream or string data. For
other sources of input, an encoding specified by
means of this attribute will override any encoding
specified in the XML declaration or the Text
declaration, or an encoding obtained from a higher
level protocol, such as HTTP [306]IETF RFC 2616].
publicId of type DOMString
The public identifier for this input source. This
may be mapped to an input source using an
implementation dependent mechanism (such as
catalogues or other mappings). The public
identifier, if specified, may also be reported as
part of the location information when errors are
reported.
stringData of type DOMString
String data to parse. If provided, this will always
be treated as a sequence of [307]16-bit units
(UTF-16 encoded characters).
systemId of type DOMString
The system identifier, a URI reference [308]IETF
RFC 2396], for this input source. The system
identifier is optional if there is a byte stream, a
character stream, or string data, but it is still
useful to provide one, since the application will
use it to resolve any relative URIs and can include
it in error messages and warnings (the
[309]LSParser will only attempt to fetch the
resource identified by the URI reference only if
there is no other input available in the input
source).
If the application knows the character encoding of
the object pointed to by the system identifier, it
can set the encoding using the encoding attribute.
If the system ID is a relative URI reference (see
section 5 in [310]IETF RFC 2396]), the DOM
implementation will attempt to resolve the relative
URI with the baseURI as the base, if that fails,
the behavior is implementation dependent.
Interface LSResourceResolver
LSResourceResolver provides a way for applications to redirect
references to external resources.
Applications needing to implement custom handling for external
resources can implement this interface and register their
implementation by setting the resourceResolver attribute of the
[311]LSParser.
The [312]LSParser 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 URN's.
Note: LSResourceResolver is based on the SAX2 [313]SAX]
EntityResolver interface.
IDL Definition
interface [314]LSResourceResolver {
[315]LSInput [316]resolveResource(in DOMString type,
in DOMString namespaceURI,
in DOMString publicId,
in DOMString systemId,
in DOMString baseURI);
};
Methods
resolveResource
Allow the application to resolve external
resources.
The [317]LSParser will call this method before
opening any external resource 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
[318]LSParser resolve the resource itself, that it
use an alternative URI, or that it use an entirely
different input source.
Application writers can use this method to redirect
external system identifiers to secure and/or local
URI's, to look up public identifiers in a
catalogue, or to read an entity from a database or
other input source (including, for example, a
dialog box).
If the system identifier is a URI, the
[319]LSParser must resolve it fully before calling
this method.
Parameters
type of type DOMString
The type of the resource being resolved. For
XML [320]XML 1.0] resources (i.e. entities),
applications must use the value
"http://www.w3.org/TR/REC-xml", for XML
Schema [321]XML Schema Part 1], applications
must use the value
"http://www.w3.org/2001/XMLSchema". Other
types of resources are outside the scope of
this specification and therefore should
recommend an absolute URI in order to use
this method.
namespaceURI of type DOMString
The namespace of the resource being resolved,
i.e. the namespace of the XML Schema
[322]XML Schema Part 1] when resolving XML
Schema resources.
publicId of type DOMString
The public identifier of the external entity
being referenced, or null if no public
identifier was supplied or if the resource is
not an entity.
systemId of type DOMString
The system identifier, a URI reference
[323]IETF RFC 2396], of the external
resource being referenced.
baseURI of type DOMString
The absolute base URI of the resource being
parsed, or null if there is no base URI.
Return Value
[324]LSInput
A [325]LSInput object describing the new input source, or null to
request that the parser open a regular URI connection to the system
identifier.
No Exceptions
Interface LSParserFilter
LSParserFilters provide applications the ability to examine
nodes as they are being constructed while parsing. 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
LSParserFilter methods, i.e. it is not possible to filter out
the document element. Document, DocumentType, Notation, Entity,
and Attr nodes are never passed to the acceptNode method on the
filter.
All validity checking while parsing 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 attributes must be present on elements when the
elements are passed to the filter methods. All other default
content must be passed to the filter methods.
The [326]LSParser ignores any exception raised in the filter.
IDL Definition
interface [327]LSParserFilter {
// Constants returned by startElement and acceptNode
const short [328]FILTER_ACCEPT = 1;
const short [329]FILTER_REJECT = 2;
const short [330]FILTER_SKIP = 3;
const short [331]FILTER_INTERRUPT = 4;
unsigned short [332]startElement(in Element elementArg);
unsigned short [333]acceptNode(in Node nodeArg);
readonly attribute unsigned long [334]whatToShow;
};
Definition group Constants returned by startElement and
acceptNode
Constants returned by startElement and acceptNode.
Defined Constants
FILTER_ACCEPT
Accept the node.
FILTER_INTERRUPT
Interrupt the normal processing of the
document.
FILTER_REJECT
Reject the node and its children.
FILTER_SKIP
Skip this single node. The children of this
node will still be considered.
Attributes
whatToShow of type unsigned long, readonly
Tells the [335]LSParser 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,
SHOW_ENTITY, and SHOW_DOCUMENT_FRAGMENT are
meaningless here, those nodes will never be passed
to a LSParserFilter.
The constants used here are defined in [336]DOM
Level 2 Traversal and Range].
Methods
acceptNode
This method will be called by the parser at the
completion of the parsing of each node. The node
and all of its descendants will exist and be
complete. The parent node will also exist, although
it may be incomplete, i.e. it may have additional
children that have not yet been parsed. Attribute
nodes are never passed to this function.
From within this method, the new node may be freely
modified - children may be added or removed, text
nodes modified, etc. The state of the rest of the
document outside this node is not defined, and the
affect of any attempt to navigate to, or to modify
any other part of the document is undefined.
For validating parsers, the checks are made on the
original document, before any modification by the
filter. No validity checks are made on any document
modifications made by the filter.
If this new node is rejected, the parser might
reuse the new node and any of its descendants.
Parameters
nodeArg of type Node
The newly constructed element. At the time
this method is called, the element is
complete - it has all of its children (and
their children, recursively) and attributes,
and is attached as a child to its parent.
Return Value
unsigned short
# FILTER_ACCEPT if this Node should be included in
the DOM document being built.
# FILTER_REJECT if the Node and all of its children
should be rejected.
# FILTER_SKIP if the Node should be skipped and the
Node should be replaced by all the children of the
Node.
# FILTER_INTERRUPT if the filter wants to stop the
processing of the document. Interrupting the
processing of the document does no longer guarantee
that the resulting DOM tree is [337]XML
well-formed. The Node is accepted and will be the
last completely parsed node.
No Exceptions
startElement
The parser will call this method after each 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.
The element node passed to 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.)
A 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.
For efficiency, the Element node passed to the
filter may not be the same one as is actually
placed in the tree if the node is accepted. And the
actual node (node object identity) may be reused
during the process of reading in and filtering a
document.
Parameters
elementArg of type Element
The newly encountered element. At the time
this method is called, the element is
incomplete - it will have its attributes, but
no children.
Return Value
unsigned short
# FILTER_ACCEPT if the Element should be included in
the DOM document being built.
# FILTER_REJECT if the Element and all of its
children should be rejected. This return value will
be ignored if element is the documentElement, the
documentElement cannot be rejected.
# FILTER_SKIP if the Element should be skipped. All
of its children are inserted in place of the
skipped Element node. This return value will be
ignored if element is the documentElement, the
documentElement cannot be skipped.
# FILTER_INTERRUPT if the filter wants to stop the
processing of the document. Interrupting the
processing of the document does no longer guarantee
that the resulting DOM tree is [338]XML
well-formed. The Element is rejected.
Returning any other values will result in unspecified behavior.
No Exceptions
Interface LSProgressEvent
This interface represents a progress event object that notifies
the application about progress as a document is parsed. It
extends the Event interface defined in [339]DOM Level 3
Events].
IDL Definition
interface [340]LSProgressEvent : events::Event {
readonly attribute [341]LSInput [342]input;
readonly attribute unsigned long [343]position;
readonly attribute unsigned long [344]totalSize;
};
Attributes
input of type [345]LSInput, readonly
The input source that is being parsed.
position of type unsigned long, readonly
The current position in the input source, including
all external entities and other resources that have
been read.
totalSize of type unsigned long, readonly
The total size of the document including all
external resources, this number might change as a
document is being parsed if references to more
external resources are seen.
Interface LSLoadEvent
This interface represents a load event object that signals the
completion of a document load.
IDL Definition
interface [346]LSLoadEvent : events::Event {
readonly attribute Document [347]newDocument;
readonly attribute [348]LSInput [349]input;
};
Attributes
input of type [350]LSInput, readonly
The input source that was parsed.
newDocument of type Document, readonly
The document that finished loading.
Interface LSSerializer
A LSSerializer provides an API for serializing (writing) a DOM
document out into XML. The XML data is written to a string or
an output stream.
During serialization of XML data, namespace fixup is done as
defined in [351]DOM Level 3 Core], Appendix B. [352]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.
LSSerializer accepts any node type for serialization. For nodes
of type Document or Entity, well-formed XML will be created
when possible (well-formedness is guaranteed if the document or
entity comes from a parse operation and is unchanged since it
was created). The serialized output for these node types is
either as a XML document or an External XML Entity,
respectively, and is acceptable input for an XML parser. For
all other types of nodes the serialized form is implementation
dependent.
Within a Document, DocumentFragment, or Entity being
serialized, Nodes are processed as follows
+ Document nodes are written, including the XML declaration
(unless the parameter "[353]xml-declaration" is set to false)
and a DTD subset, if one exists in the DOM. Writing a
Document node serializes the entire document.
+ Entity nodes, when written directly by
[354]LSSerializer.write, outputs the entity expansion but no
namespace fixup is done. The resulting output will be valid
as an external entity.
+ EntityReference nodes are serialized as an entity reference
of the form "&entityName;" in the output. Child nodes (the
expansion) of the entity reference are ignored.
+ CDATA sections containing content characters that cannot be
represented in the specified output encoding are handled
according to the "[355] split-cdata-sections" parameter.
If the parameter is set to 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.
If the parameter is set to false, unrepresentable characters
in a CDATA section are reported as
"invalid-data-in-cdata-section" errors. The error is not
recoverable - there is no mechanism for supplying alternative
characters and continuing with the serialization.
+ DocumentFragment nodes are serialized by serializing the
children of the document fragment in the order they appear in
the document fragment.
+ All other node types (Element, Text, etc.) are serialized to
their corresponding XML source form.
[355] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-split-cdata-sections
Note: The serialization of a Node does not always generate a
[356]well-formed XML document, i.e. a [357]LSParser might throw
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 (>, ', and ") might not be
used, except where needed (e.g. using > in cases such as
']]>'). Any characters that cannot be represented directly in
the output character encoding are serialized as numeric
character references (and since character encoding standards
commonly use hexadecimal representations of characters, using
the hexadecimal representation when serializing character
references is encouraged).
To allow attribute values to contain both single and double
quotes, the apostrophe or single-quote character (') may be
represented as "'", and the double-quote character (") as
""". New line characters and other characters that cannot
be represented directly in attribute values in the output
character encoding are 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 a fatal error. An example would be
serializing the element with encoding="us-ascii".
When requested by setting the parameter "[358]
normalize-characters" on LSSerializer to true, character
normalization is performed according to the rules defined in
[359]CharModel] on all data to be serialized, both markup and
character data. The character 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.
[358] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-normalize-characters
When outputting unicode data, whether or not a byte order mark
is serialized, or if the output is big-endian or little-endian,
is implementation dependent.
Namespaces are fixed up during serialization, the serialization
process will verify that namespace declarations, namespace
prefixes and the namespace URI's associated with elements and
attributes are consistent. If inconsistencies are found, the
serialized form of the document will be altered to remove them.
The method used for doing the namespace fixup while serializing
a document is the algorithm defined in Appendix B.1, "Namespace
normalization", of [360]DOM Level 3 Core].
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.
Issue LSSerializer-change-DOM:
We may take back what we say in the above paragraph
depending on feedback from implementors, but for now the
belief is that the DOM's view of the document is not
changed during serialization.
While serializing a document, the parameter
"[361]discard-default-content" controls whether or not
non-specified data is serialized.
While serializing, errors and warnings are reported to the
application through the error handler
([362]LSSerializer.config's "[363] error-handler" parameter).
This specification does in no way try to define all possible
errors and warnings that can occur while serializing a DOM
node, but some common error and warning cases are defined. The
types (DOMError.type) of errors and warnings defined by this
specification are:
[363] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler
"invalid-data-in-cdata-section" [fatal]
Raised if the configuration parameter "[364]
split-cdata-sections" is set to false and invalid data is
encountered in a CDATA section.
[364] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-split-cdata-sections
"no-output-specified" [fatal]
Raised when writing to a [365]LSOutput if no output is
specified in the [366]LSOutput.
"unbound-prefix-in-entity-reference" [fatal]
Raised if the configuration parameter "[367] namespaces"
is set to true and an entity whose replacement text
contains unbound namespace prefixes is referenced in a
location where there are no bindings for the namespace
prefixes.
[367] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces
"unsupported-encoding" [fatal]
Raised if an unsupported encoding is encountered.
In addition to raising the defined errors and warnings,
implementations are expected to raise implementation specific
errors and warnings for any other error and warning cases such
as IO errors (file not found, permission denied,...) and so on.
IDL Definition
interface [368]LSSerializer {
readonly attribute DOMConfiguration [369]config;
attribute DOMString [370]newLine;
attribute [371]LSSerializerFilter [372]filter;
boolean [373]write(in Node nodeArg,
in [374]LSOutput destination);
boolean [375]writeToURI(in Node nodeArg,
in DOMString uri);
DOMString [376]writeToString(in Node nodeArg)
raises(DOMException);
};
Attributes
config of type DOMConfiguration, readonly
The DOMConfiguration object used by the
LSSerializer when serializing a DOM node.
In addition to the parameters recognized in the
[377]DOM Level 3 Core], the DOMConfiguration
objects for LSSerializer adds, or modifies, the
following parameters:
"canonical-form"
true
[optional]
This formatting writes the document
according to the rules specified in
[378]Canonical XML]. Setting this
parameter to true will set the
parameter "[379]format-pretty-print" to
false.
false
[required] (default)
Do not canonicalize the output.
"discard-default-content"
true
[required] (default)
Use the Attr.specified attribute to
decide what attributes should be
discarded. Note that some
implementations might use whatever
information available to the
implementation (i.e. XML schema, DTD,
the Attr.specified attribute, and so
on) to determine what attributes and
content to discard if this parameter is
set to true.
false
[required]
Keep all attributes and all content.
"format-pretty-print"
true
[optional]
Formatting the output by adding
whitespace to produce a pretty-printed,
indented, human-readable form. The
exact form of the transformations is
not specified by this specification.
Pretty-printing changes the content of
the document and may affect the
validity of the document, validating
implementations should preserve
validity. Setting this parameter to
true will set the parameter "[380]
canonical-form" to false.
[380] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-canonical-form
false
[required] (default)
Don't pretty-print the result.
"ignore-unknown-character-denormalizations"
true
[required] (default)
If, while verifying full normalization
when [381]XML 1.1] is supported, a
character is encountered for which the
normalization properties cannot be
determined, then raise a
"unknown-character-denormalization"
warning (instead of raising an error,
if this parameter is not set) and
ignore any possible denormalizations
caused by these characters.
Issue LSSerializer-iucd-issue:
IMO it would make sense to move
this parameter into the DOM Level
3 Core spec, and the
error/warning should be defined
there.
false
[optional]
Report an fatal error if a character is
encountered for which the processor
cannot determine the normalization
properties.
"normalize-characters"
This parameter is equivalent to the one
defined by DOMConfiguration in [382]DOM
Level 3 Core]. Unlike in the Core, the
default value for this parameter is true.
While DOM implementations are not required to
support fully normalizing the characters in
the document according to the rules defined
in [383]CharModel] supplemented by the
definitions of relevant constructs from
Section 2.13 of [384]XML 1.1], this
parameter must be activated by default if
supported.
"xml-declaration"
true
[required] (default)
If a Document, Element, or Entity node
is serialized, the XML declaration, or
text declaration, should be included.
The version (Document.xmlVersion if the
document is a Level 3 document and the
version is non-null, otherwise use the
value "1.0"), and the output encoding
(see [385]LSSerializer.write for
details on how to find the output
encoding) are specified in the
serialized XML declaration.
false
[required]
Do not serialize the XML and text
declarations. Report a
"xml-declaration-needed" warning if
this will cause problems (i.e. the
serialized data is of an XML version
other than [386]XML 1.0], or an
encoding would be needed to be able to
re-parse the serialized data).
The parameters "[387] well-formed", "[388]
namespaces", and "[389] namespace-declarations"
cannot be set to false.
[387] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-well-formed
[388] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces
[389] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespace-declarations
filter of type [390]LSSerializerFilter
When the application provides a filter, the
serializer will call out to the filter before
serializing each Node. The filter implementation
can choose to remove the node from the stream or to
terminate the serialization early.
The filter is invoked before the operations
requested by the DOMConfiguration parameters have
been applied. For example, CDATA sections are
passed to the filter even if "[391] cdata-sections"
is set to false.
[391] http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-cdata-sections
newLine of type DOMString
The end-of-line sequence of characters to be used
in the XML being written out. Any string is
supported, but these are the recommended
end-of-line sequences (using other character
sequences than these recommended ones can result in
a document that is either not serializable or not
well-formed):
null
Use a default end-of-line sequence. DOM
implementations should choose the default to
match the usual convention for text files in
the environment being used. Implementations
must choose a default sequence that matches
one of those allowed by section 2.11,
"End-of-Line Handling" in [392]XML 1.0], if
the serialized content is XML 1.0 or section
2.11, "End-of-Line Handling" in [393]XML
1.1], if the serialized content is XML 1.1.
CR
The carriage-return character (#xD).
CR-LF
The carriage-return and line-feed characters
(#xD #xA).
LF
The line-feed character (#xA).
The default value for this attribute is null.
Methods
write
Serialize the specified node as described above in
the general description of the LSSerializer
interface. The output is written to the supplied
[394]LSOutput.
When writing to a [395]LSOutput, the encoding is
found by looking at the encoding information that
is reachable through the [396]LSOutput and the item
to be written (or its owner document) in this
order:
1. [397]LSOutput.encoding,
2. Document.actualEncoding,
3. Document.xmlEncoding.
If no encoding is reachable through the above
properties, a default encoding of "UTF-8" will be
used.
If the specified encoding is not supported an
"unsupported-encoding" fatal error is raised. When
outputting XML data, implementations are required
to support the encodings "UTF-8", "UTF-16BE", and
"UTF-16LE" to guarantee that data is serializable
in all encodings that are required to be supported
by all XML parsers.
If no output is specified in the [398]LSOutput, a
"no-output-specified" fatal error is raised.
The implementation is responsible of associating
the appropriate media type with the serialized
data.
When writing to a HTTP URI, a HTTP PUT is
performed. When writing to other types of URIs, the
mechanism for writing the data to the URI is
implementation dependent.
Parameters
nodeArg of type Node
The node to serialize.
destination of type [399]LSOutput
The destination for the serialized DOM.
Return Value
boolean
Returns true if node was successfully serialized and false in case the
node couldn't be serialized.
No Exceptions
writeToString
Serialize the specified node as described above in
the general description of the LSSerializer
interface. The output is written to a DOMString
that is returned to the caller (this method
completely ignores all the encoding information
available).
Parameters
nodeArg of type Node
The node to serialize.
Return Value
DOMString
Returns the serialized data, or null in case the node couldn't be
serialized.
Exceptions
DOMException
DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to fit
in a DOMString.
writeToURI
A convenience method that acts as if
[400]LSSerializer.write was called with a
[401]LSOutput with no encoding specified and
[402]LSOutput.systemId set to the uri argument.
Parameters
nodeArg of type Node
The node to serialize.
uri of type DOMString
The URI to write to.
Return Value
boolean
Returns true if node was successfully serialized and false in case the
node couldn't be serialized.
No Exceptions
Interface LSOutput
This interface represents an output destination for data.
This interface allows an application to encapsulate information
about an output destination in a single object, which may
include a URI, a byte stream (possibly with a specified
encoding), a base URI, and/or a character stream.
The exact definitions of a byte stream and a character stream
are binding dependent.
The application is expected to provide objects that implement
this interface whenever such objects are needed. The
application can either provide its own objects that implement
this interface, or it can use the generic factory method
[403]DOMImplementationLS.createLSOutput() to create objects
that implement this interface.
The [404]LSSerializer will use the LSOutput object to determine
where to serialize the output to. The [405]LSSerializer will
look at the different outputs specified in the LSOutput in the
following order to know which one to output to, the first one
that is not null and not an empty string will be used:
1. [406]LSOutput.characterStream
2. [407]LSOutput.byteStream
3. [408]LSOutput.systemId
LSOutput objects belong to the application. The DOM
implementation will never modify them (though it may make
copies and modify the copies, if necessary).
IDL Definition
interface [409]LSOutput {
// Depending on the language binding in use,
// this attribute may not be available.
attribute [410]LSWriter [411]characterStream;
attribute [412]LSOutputStream [413]byteStream;
attribute DOMString [414]systemId;
attribute DOMString [415]encoding;
};
Attributes
byteStream of type [416]LSOutputStream
An attribute of a language and binding dependent
type that represents a writable stream of bytes.
characterStream of type [417]LSWriter
Depending on the language binding in use, this
attribute may not be available.
An attribute of a language and binding dependent
type that represents a writable stream to which
[418]16-bit units can be output.
encoding of type DOMString
The character encoding to use for the output. The
encoding must be a string acceptable for an XML
encoding declaration ([419]XML 1.0] section 4.3.3
"Character Encoding in Entities"), it is
recommended that character encodings registered (as
charsets) with the Internet Assigned Numbers
Authority [420]IANA-CHARSETS] should be referred
to using their registered names.
This attribute has no effect when outputting to a
character stream.
systemId of type DOMString
The system identifier, a URI reference [421]IETF
RFC 2396], for this output destination.
If the system ID is a relative URI reference (see
section 5 in [422]IETF RFC 2396]), the behavior is
implementation dependent.
Interface LSSerializerFilter
LSSerializerFilters provide applications the ability to examine
nodes as they are being serialized and decide what nodes should
be serialized or not. The LSSerializerFilter interface is based
on the NodeFilter interface defined in [423]DOM Level 2
Traversal and Range].
Document, DocumentType, DocumentFragment, Notation, and Entity
nodes are not passed to the filter.
When serializing an Element, the element is passed to the
filter before any of its attributes are passed to the filter.
Namespace declaration attributes, and default attributes
(except in the case when "[424]discard-default-content" is set
to false), are never passed to the filter.
The result of any attempt to modify a node passed to a
LSSerializerFilter is implementation dependent.
IDL Definition
interface [425]LSSerializerFilter : traversal::NodeFilter {
readonly attribute unsigned long [426]whatToShow;
};
Attributes
whatToShow of type unsigned long, readonly
Tells the [427]LSSerializer what types of nodes to
show to the filter. See NodeFilter for definition
of the constants. The constants SHOW_DOCUMENT,
SHOW_DOCUMENT_TYPE, SHOW_DOCUMENT_FRAGMENT,
SHOW_NOTATION, and SHOW_ENTITY are meaningless
here, such nodes will never be passed to a
LSSerializerFilter.
The constants used here are defined in [428]DOM
Level 2 Traversal and Range].
07 November 2003
Appendix A: IDL Definitions
This appendix contains the complete OMG IDL [429]OMG IDL] for the
Level 3 Document Object Model Abstract Schemas and Load and Save
definitions.
The IDL files are also available as:
[430]http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/idl.zip
[430] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/idl.zip
[431]ls.idl:
[431] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/idl/ls.idl
// 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 [432]LSInputStream;
typedef Object [433]LSOutputStream;
typedef Object [434]LSReader;
typedef Object [435]LSWriter;
typedef dom::DOMString DOMString;
typedef dom::DOMConfiguration DOMConfiguration;
typedef dom::Node Node;
typedef dom::Document Document;
typedef dom::Element Element;
interface LSParser;
interface LSSerializer;
interface LSInput;
interface LSOutput;
interface LSParserFilter;
interface LSSerializerFilter;
interface [436]DOMImplementationLS {
// DOMImplementationLSMode
const unsigned short [437]MODE_SYNCHRONOUS = 1;
const unsigned short [438]MODE_ASYNCHRONOUS = 2;
[439]LSParser [440]createLSParser(in unsigned short mode,
in DOMString schemaType)
raises(dom::DOMException);
[441]LSSerializer [442]createLSSerializer();
[443]LSInput [444]createLSInput();
[445]LSOutput [446]createLSOutput();
};
interface [447]LSParser {
readonly attribute DOMConfiguration [448]config;
attribute [449]LSParserFilter [450]filter;
readonly attribute boolean [451]async;
readonly attribute boolean [452]busy;
Document [453]parse(in [454]LSInput input)
raises(dom::DOMException);
Document [455]parseURI(in DOMString uri)
raises(dom::DOMException);
// ACTION_TYPES
const unsigned short [456]ACTION_APPEND_AS_CHILDREN = 1;
const unsigned short [457]ACTION_REPLACE_CHILDREN = 2;
const unsigned short [458]ACTION_INSERT_BEFORE = 3;
const unsigned short [459]ACTION_INSERT_AFTER = 4;
const unsigned short [460]ACTION_REPLACE = 5;
Node [461]parseWithContext(in [462]LSInput input,
in Node contextArg,
in unsigned short action)
raises(dom::DOMException);
void [463]abort();
};
interface [464]LSInput {
// Depending on the language binding in use,
// this attribute may not be available.
attribute [465]LSReader [466]characterStream;
attribute [467]LSInputStream [468]byteStream;
attribute DOMString [469]stringData;
attribute DOMString [470]systemId;
attribute DOMString [471]publicId;
attribute DOMString [472]baseURI;
attribute DOMString [473]encoding;
attribute boolean [474]certifiedText;
};
interface [475]LSResourceResolver {
[476]LSInput [477]resolveResource(in DOMString type,
in DOMString namespaceURI,
in DOMString publicId,
in DOMString systemId,
in DOMString baseURI);
};
interface [478]LSParserFilter {
// Constants returned by startElement and acceptNode
const short [479]FILTER_ACCEPT = 1;
const short [480]FILTER_REJECT = 2;
const short [481]FILTER_SKIP = 3;
const short [482]FILTER_INTERRUPT = 4;
unsigned short [483]startElement(in Element elementArg);
unsigned short [484]acceptNode(in Node nodeArg);
readonly attribute unsigned long [485]whatToShow;
};
interface [486]LSSerializer {
readonly attribute DOMConfiguration [487]config;
attribute DOMString [488]newLine;
attribute [489]LSSerializerFilter [490]filter;
boolean [491]write(in Node nodeArg,
in [492]LSOutput destination);
boolean [493]writeToURI(in Node nodeArg,
in DOMString uri);
DOMString [494]writeToString(in Node nodeArg)
raises(dom::DOMException);
};
interface [495]LSOutput {
// Depending on the language binding in use,
// this attribute may not be available.
attribute [496]LSWriter [497]characterStream;
attribute [498]LSOutputStream [499]byteStream;
attribute DOMString [500]systemId;
attribute DOMString [501]encoding;
};
interface [502]LSProgressEvent : events::Event {
readonly attribute [503]LSInput [504]input;
readonly attribute unsigned long [505]position;
readonly attribute unsigned long [506]totalSize;
};
interface [507]LSLoadEvent : events::Event {
readonly attribute Document [508]newDocument;
readonly attribute [509]LSInput [510]input;
};
interface [511]LSSerializerFilter : traversal::NodeFilter {
readonly attribute unsigned long [512]whatToShow;
};
};
#endif // _LS_IDL_
07 November 2003
Appendix B: Java Language Binding
This appendix contains the complete Java [513]Java] bindings for the
Level 3 Document Object Model Load and Save.
The Java files are also available as
[514]http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/java-binding
.zip
[514] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/java-binding.zip
org/w3c/dom/ls/DOMImplementationLS.java:
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 LSParser createLSParser(short mode,
String schemaType)
throws DOMException;
public LSSerializer createLSSerializer();
public LSInput createLSInput();
public LSOutput createLSOutput();
}
org/w3c/dom/ls/LSParser.java:
package org.w3c.dom.ls;
import org.w3c.dom.Document;
import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
public interface LSParser {
public DOMConfiguration getConfig();
public LSParserFilter getFilter();
public void setFilter(LSParserFilter filter);
public boolean getAsync();
public boolean getBusy();
public Document parse(LSInput input)
throws DOMException;
public Document parseURI(String uri)
throws DOMException;
// ACTION_TYPES
public static final short ACTION_APPEND_AS_CHILDREN = 1;
public static final short ACTION_REPLACE_CHILDREN = 2;
public static final short ACTION_INSERT_BEFORE = 3;
public static final short ACTION_INSERT_AFTER = 4;
public static final short ACTION_REPLACE = 5;
public Node parseWithContext(LSInput input,
Node contextArg,
short action)
throws DOMException;
public void abort();
}
org/w3c/dom/ls/LSInput.java:
package org.w3c.dom.ls;
public interface LSInput {
public java.io.Reader getCharacterStream();
public void setCharacterStream(java.io.Reader characterStream);
public java.io.InputStream getByteStream();
public void setByteStream(java.io.InputStream byteStream);
public String getStringData();
public void setStringData(String stringData);
public String getSystemId();
public void setSystemId(String systemId);
public String getPublicId();
public void setPublicId(String publicId);
public String getBaseURI();
public void setBaseURI(String baseURI);
public String getEncoding();
public void setEncoding(String encoding);
public boolean getCertifiedText();
public void setCertifiedText(boolean certifiedText);
}
org/w3c/dom/ls/LSResourceResolver.java:
package org.w3c.dom.ls;
public interface LSResourceResolver {
public LSInput resolveResource(String type,
String namespaceURI,
String publicId,
String systemId,
String baseURI);
}
org/w3c/dom/ls/LSParserFilter.java:
package org.w3c.dom.ls;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
public interface LSParserFilter {
// 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 elementArg);
public short acceptNode(Node nodeArg);
public int getWhatToShow();
}
org/w3c/dom/ls/LSProgressEvent.java:
package org.w3c.dom.ls;
import org.w3c.dom.events.Event;
public interface LSProgressEvent extends Event {
public LSInput getInput();
public int getPosition();
public int getTotalSize();
}
org/w3c/dom/ls/LSLoadEvent.java:
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 LSInput getInput();
}
org/w3c/dom/ls/LSSerializer.java:
package org.w3c.dom.ls;
import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
public interface LSSerializer {
public DOMConfiguration getConfig();
public String getNewLine();
public void setNewLine(String newLine);
public LSSerializerFilter getFilter();
public void setFilter(LSSerializerFilter filter);
public boolean write(Node nodeArg,
LSOutput destination);
public boolean writeToURI(Node nodeArg,
String uri);
public String writeToString(Node nodeArg)
throws DOMException;
}
org/w3c/dom/ls/LSOutput.java:
package org.w3c.dom.ls;
public interface LSOutput {
public java.io.Writer getCharacterStream();
public void setCharacterStream(java.io.Writer characterStream);
public java.io.OutputStream getByteStream();
public void setByteStream(java.io.OutputStream byteStream);
public String getSystemId();
public void setSystemId(String systemId);
public String getEncoding();
public void setEncoding(String encoding);
}
org/w3c/dom/ls/LSSerializerFilter.java:
package org.w3c.dom.ls;
import org.w3c.dom.traversal.NodeFilter;
public interface LSSerializerFilter extends NodeFilter {
public int getWhatToShow();
}
07 November 2003
Appendix C: ECMAScript Language Binding
This appendix contains the complete ECMAScript [515]ECMAScript]
binding for the Level 3 Document Object Model Load and Save
definitions.
Properties of the DOMImplementationLS Constructor function:
DOMImplementationLS.MODE_SYNCHRONOUS
The value of the constant
DOMImplementationLS.MODE_SYNCHRONOUS is 1.
DOMImplementationLS.MODE_ASYNCHRONOUS
The value of the constant
DOMImplementationLS.MODE_ASYNCHRONOUS is 2.
Objects that implement the DOMImplementationLS interface:
Functions of objects that implement the DOMImplementationLS
interface:
createLSParser(mode, schemaType)
This function returns an object that implements the
LSParser interface.
The mode parameter is a Number.
The schemaType parameter is a String.
This function can raise an object that implements
the DOMException interface.
createLSSerializer()
This function returns an object that implements the
LSSerializer interface.
createLSInput()
This function returns an object that implements the
LSInput interface.
createLSOutput()
This function returns an object that implements the
LSOutput interface.
Properties of the LSParser Constructor function:
LSParser.ACTION_APPEND_AS_CHILDREN
The value of the constant
LSParser.ACTION_APPEND_AS_CHILDREN is 1.
LSParser.ACTION_REPLACE_CHILDREN
The value of the constant
LSParser.ACTION_REPLACE_CHILDREN is 2.
LSParser.ACTION_INSERT_BEFORE
The value of the constant LSParser.ACTION_INSERT_BEFORE
is 3.
LSParser.ACTION_INSERT_AFTER
The value of the constant LSParser.ACTION_INSERT_AFTER is
4.
LSParser.ACTION_REPLACE
The value of the constant LSParser.ACTION_REPLACE is 5.
Objects that implement the LSParser interface:
Properties of objects that implement the LSParser interface:
config
This read-only property is an object that
implements the DOMConfiguration interface.
filter
This property is an object that implements the
LSParserFilter interface.
async
This read-only property is a Boolean.
busy
This read-only property is a Boolean.
Functions of objects that implement the LSParser interface:
parse(input)
This function returns an object that implements the
Document interface.
The input parameter is an object that implements
the LSInput interface.
This function can raise an object that implements
the DOMException interface.
parseURI(uri)
This function returns an object that implements the
Document interface.
The uri parameter is a String.
This function can raise an object that implements
the DOMException interface.
parseWithContext(input, contextArg, action)
This function returns an object that implements the
Node interface.
The input parameter is an object that implements
the LSInput interface.
The contextArg parameter is an object that
implements the Node interface.
The action parameter is a Number.
This function can raise an object that implements
the DOMException interface.
abort()
This function has no return value.
Objects that implement the LSInput interface:
Properties of objects that implement the LSInput interface:
byteStream
This property is an object that implements the
Object interface.
stringData
This property is a String.
systemId
This property is a String.
publicId
This property is a String.
baseURI
This property is a String.
encoding
This property is a String.
certifiedText
This property is a Boolean.
Objects that implement the LSResourceResolver interface:
Functions of objects that implement the LSResourceResolver
interface:
resolveResource(type, namespaceURI, publicId, systemId,
baseURI)
This function returns an object that implements the
LSInput interface.
The type parameter is a String.
The namespaceURI parameter is a String.
The publicId parameter is a String.
The systemId parameter is a String.
The baseURI parameter is a String.
Properties of the LSParserFilter Constructor function:
LSParserFilter.FILTER_ACCEPT
The value of the constant LSParserFilter.FILTER_ACCEPT is
1.
LSParserFilter.FILTER_REJECT
The value of the constant LSParserFilter.FILTER_REJECT is
2.
LSParserFilter.FILTER_SKIP
The value of the constant LSParserFilter.FILTER_SKIP is
3.
LSParserFilter.FILTER_INTERRUPT
The value of the constant LSParserFilter.FILTER_INTERRUPT
is 4.
Objects that implement the LSParserFilter interface:
Properties of objects that implement the LSParserFilter
interface:
whatToShow
This read-only property is a Number.
Functions of objects that implement the LSParserFilter interface:
startElement(elementArg)
This function returns a Number.
The elementArg parameter is an object that
implements the Element interface.
acceptNode(nodeArg)
This function returns a Number.
The nodeArg parameter is an object that implements
the Node interface.
Objects that implement the LSProgressEvent interface:
Objects that implement the LSProgressEvent interface have all
properties and functions of the Event interface as well
as the properties and functions defined below.
Properties of objects that implement the LSProgressEvent
interface:
input
This read-only property is an object that
implements the LSInput interface.
position
This read-only property is a Number.
totalSize
This read-only property is a Number.
Objects that implement the LSLoadEvent interface:
Objects that implement the LSLoadEvent interface have all
properties and functions of the Event interface as well
as the properties and functions defined below.
Properties of objects that implement the LSLoadEvent interface:
newDocument
This read-only property is an object that
implements the Document interface.
input
This read-only property is an object that
implements the LSInput interface.
Objects that implement the LSSerializer interface:
Properties of objects that implement the LSSerializer interface:
config
This read-only property is an object that
implements the DOMConfiguration interface.
newLine
This property is a String.
filter
This property is an object that implements the
LSSerializerFilter interface.
Functions of objects that implement the LSSerializer interface:
write(nodeArg, destination)
This function returns a Boolean.
The nodeArg parameter is an object that implements
the Node interface.
The destination parameter is an object that
implements the LSOutput interface.
writeToURI(nodeArg, uri)
This function returns a Boolean.
The nodeArg parameter is an object that implements
the Node interface.
The uri parameter is a String.
writeToString(nodeArg)
This function returns a String.
The nodeArg parameter is an object that implements
the Node interface.
This function can raise an object that implements
the DOMException interface.
Objects that implement the LSOutput interface:
Properties of objects that implement the LSOutput interface:
byteStream
This property is an object that implements the
Object interface.
systemId
This property is a String.
encoding
This property is a String.
Objects that implement the LSSerializerFilter interface:
Objects that implement the LSSerializerFilter interface have all
properties and functions of the NodeFilter interface as
well as the properties and functions defined below.
Properties of objects that implement the LSSerializerFilter
interface:
whatToShow
This read-only property is a Number.
07 November 2003
Appendix D: Acknowledgements
Many people contributed to the DOM specifications (Level 1, 2 or 3),
including participants 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 and
invited expert), 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!).
Many thanks to Elliotte Rusty Harold, Andrew Clover, Anjana Manian,
Christian Parpart, Mikko Honkala, and François Yergeau for their
review and comments of this document.
Special thanks to the [516]DOM Conformance Test Suites contributors:
Fred Drake, Mary Brady (NIST), Rick Rivello (NIST), Robert Clary
(Netscape), with a special mention to Curt Arnold.
[516] http://www.w3.org/DOM/Test
D.1 Production Systems
This specification was written in XML. The HTML, OMG IDL, Java and
ECMAScript bindings were all produced automatically.
Thanks to Joe English, author of [517]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.
[517] http://www.flightlab.com/cost
After DOM Level 1, we used [518]Xerces as the basis DOM implementation
and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors
wrote the [519]Java programs which are the DOM application.
[518] http://xml.apache.org/xerces-j
[519] http://dev.w3.org/cvsweb/java/classes/org/w3c/tools/specgenerator/
Thanks also to Jan Kärrman, author of [520]html2ps, which we use in
creating the PostScript version of the specification.
[520] http://user.it.uu.se/~jan/html2ps.html
07 November 2003
Glossary
Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)
Some 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.
16-bit unit
The base unit of a 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.
API
An API is an Application Programming Interface, a set of
functions or methods used to access some functionality.
namespace well-formed
A node is a namespace well-formed XML node if it is a
[521]well-formed node, and follows the productions and
namespace constraints. If [522]XML 1.0] is used, the
constraints are defined in [523]XML Namespaces]. If [524]XML
[1] is used, the constraints are defined in [525]XML
Namespaces 1.1].
[1] http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/copyright-notice.html
read only node
A read only node is a node that is immutable. This means its
list of children, its content, and its attributes, when it is
an element, cannot be changed in any way. However, a read only
node can possibly be moved, when it is not itself contained in
a read only node.
schema
A schema defines a set of structural and value constraints
applicable to XML documents. Schemas can be expressed in schema
languages, such as DTD, XML Schema, etc.
well-formed
A node is a well-formed XML node if its serialized form,
without doing any transformation during its serialization,
matches its respective production in [526]XML 1.0] or
[527]XML 1.1] (depending on the XML version in use) with all
well-formedness constraints related to that production, and if
the entities which are referenced within the node are also
well-formed. If namespaces for XML are in use, the node must
also be [528]namespace well-formed.
07 November 2003