- Interface DOMImplementationLS
-
DOMImplementationLS contains the factory methods
for creating objects that implement the DOMBuilder
(parser) and DOMWriter
(serializer) interfaces.
An object that implements DOMImplementationLS is obtained by
doing a binding specific cast from DOMImplementation to
DOMImplementationLS. Implementations supporting the Load and Save
feature must implement the DOMImplementationLS interface on
whatever object implements the DOMImplementation interface.
IDL Definition-
interface DOMImplementationLS {
// DOMIMplementationLSMode
const unsigned short MODE_SYNCHRONOUS = 1;
const unsigned short MODE_ASYNCHRONOUS = 2;
DOMBuilder createDOMBuilder(in unsigned short mode)
raises(DOMException);
DOMWriter createDOMWriter();
DOMInputSource createDOMInputSource();
};
- Definition group DOMIMplementationLSMode
-
An integer indicating which type of mode this is.
- Defined Constants
-
MODE_ASYNCHRONOUS- Create an asynchronous
DOMBuilder.
MODE_SYNCHRONOUS- Create a synchronous
DOMBuilder.
- Methods
-
createDOMBuilder-
Create a new
DOMBuilder.
The newly constructed parser may then be configured by means of its
setFeature method, and used to parse documents by
means of its
parse method.
Parameters
mode of type unsigned
short- The
mode argument is either
MODE_SYNCHRONOUS or MODE_ASYNCHRONOUS, if
mode is MODE_SYNCHRONOUS then the DOMBuilder
that is created will operate in synchronous mode, if it's
MODE_ASYNCHRONOUS then the DOMBuilder
that is created will operate in asynchronous mode.
Exceptions
|
DOMException
|
Raise a NOT_SUPPORTED_ERR exception if MODE_ASYNCHRONOUS is not
supported.
|
createDOMInputSource-
createDOMWriter-
Create a new
DOMWriter
object.
DOMWriters
are used to serialize a DOM tree back into an XML document.
No Parameters
No Exceptions
- Interface DOMBuilder
-
A interface to an object that is able to build a DOM tree from
various input sources.
DOMBuilder provides an API for parsing XML
documents and building the corresponding DOM document tree. A
DOMBuilder instance is obtained from the DOMImplementationLS
interface by invoking its createDOMBuildermethod.
As specified in [DOM Level 3 Core], when a document is
first made available via the DOMBuilder:
- there is only one
Text node for each block of
text. The Text nodes are into "normal" form: only
structure (e.g., elements, comments, processing instructions, CDATA
sections, and entity references) separates Text nodes,
i.e., there are neither adjacent Text nodes nor empty
Text nodes.
- it is expected that the
value and
nodeValue attributes of an Attr node
initially return the XML
1.0 normalized value. However, if the features
validate-if-schema and
datatype-normalization are set to true,
depending on the attribute normalization used, the attribute values
may differ from the ones obtained by the XML 1.0 attribute
normalization. If the feature
datatype-normalization is not set to
true, the XML 1.0 attribute normalization is garantee
to occur, and if attributes list does not contain namespace
declarations, the attributes attribute on
Element node represents the property [attributes]
defined in [XML Information set] .
- Issue Infoset:
- XML Schemas does not modified the XML attribute normalization
but represents their normalized value in an other information item
property: [schema normalized value]
Resolution: XML Schema normalization only occurs if
datatype-normalization is set to
true.
The Document Object Model Level 3 Load and Save does not provide
a way to disable the namespace resolution: Namespaces are always
taken into account during loading and saving operations.
Asynchronous DOMBuilder objects are expected to
also implement the events::EventTarget interface so
that event listeners can be registerd on asynchronous
DOMBuilder objects.
Events supported by asynchronous DOMBuilder
are:
- ls-load: The document that's being loaded is completely
parsed, see the definition of
LSLoadEvent
- ls-progress: Progress notification, see the definition
of
LSProgressEvent
DOMBuilders have a number of named features that
can be queried or set. The name of DOMBuilder features
must be valid XML names. Implementation specific features
(extensions) should choose a implementation specific prefix to
avoid name collisions.
Even if all features must be recognized by all implementations,
being able to set a state (true or false)
is not always required. The following list of recognized features
indicates the definitions of each feature state, if setting the
state to true or false must be supported
or is optional and, which state is the default one:
"namespace-declarations"-
true- [required] (default)
include the namespace declaration attributes, specified or
defaulted from the schema or the DTD, in the DOM document. See also
the section Declaring
Namespaces in [XML Namespaces].
false- [optional]
discard all namespace declaration attributes. The Namespace
prefixes will be retained even if this feature is set to
false.
"validation"-
true- [optional]
report validation errors (setting true also will
force the external-general-entities and
external-parameter-entities features to be
true.) Also note that the
validate-if-schema feature will alter the validation
behavior when this feature is set true.
false- [required] (default)
do not report validation errors.
"external-parameter-entities"-
true- [required] (default)
load external parameter entities.
false- [optional]
do not load external parameter entities.
- default value
true
"external-general-entities"-
true- [required] (default)
include all external general (text) entities.
false- [optional]
do not include external general entities.
"external-dtd-subset"-
true- [required] (default)
load the external dtd and also all external parameter
entities.
false- [optional]
do not load the dtd nor external parameter entities.
"validate-if-schema"-
true- [optional]
when both this feature and validation are true,
enable validation only if the document being processed has a schema
(i.e. XML schema, DTD, any other type of schema, note that this is
unrelated to the abstract schema specification). Documents without
schemas are parsed without validation.
false- [required] (default)
the validation feature alone controls whether the document is
checked for validity. Documents without a schemas are not
valid.
"validate-against-dtd"-
true- [optional]
Prefere validation against the DTD over any other schema
referenced in the XML file.
false- [required] (default)
Let the parser decide what to validate against if there are
references to multiple types of schemas.
"datatype-normalization"-
true- [required]
Let the (non-DTD) validation process do its datatype normalization
that is defined in the used schema language.
- Issue normalization-1:
- We should define "datatype normalization".
false- [required] (default)
Disable datatype normalization. The XML 1.0 attribute value
normalization is garantee to occur in that case.
"create-entity-ref-nodes"-
true- [required] (default)
Create EntityReference nodes in the DOM document. It
will also set create-entity-nodes to be
true.
false- [optional]
omit all EntityReference nodes from the DOM document,
putting the entity expansions directly in their place.
Text nodes are into "normal" form.
EntityReference nodes to non-defined entities will
still be created in the DOM document.
"create-entity-nodes"-
true- [required] (default)
Create Entity nodes in the DOM document.
false- [optional]
Omit all entity nodes from the DOM document. It will
also set create-entity-ref-nodes to
false.
"whitespace-in-element-content"-
true- [required] (default)
Include white space characters appearing within element content
(see [XML] 2.10 "White Space Handling").
false- [optional]
Omit white space characters appearing within element content. Note
that white space characters within element content will only be
omitted if it can be identified as such, and not all parsers may be
able to do so (see [XML] 2.10 "White Space Handling").
"create-cdata-nodes"-
true- [required] (default)
Create CDATASection nodes in response to the
appearance of CDATA sections in the XML document.
false- [optional]
Do not create CDATASection nodes in the DOM
document.
The content of any CDATA sections in the XML document appears in
the DOM as if it had been normal (non-CDATA) content. If a CDATA
section is adjacent to other content, the combined content appears
in a single Text node, i.e. the Text
nodes are into "normal" form.
"comments"-
true- [required] (default)
Include XML comments in the DOM document.
false- [required]
Discard XML comments, do not create Comment nodes in
the DOM Document resulting from a parse.
"charset-overrides-xml-encoding"-
true- [required] (default)
If a higher level protocol such as HTTP [RFC2616]
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 [XML] 4.3.3
"Character Encoding in Entities"). Explicitly setting an encoding
in the DOMInputSource
overrides encodings from the protocol.
false- [required]
Any character set encoding information from higher level protocols
is ignored by the parser.
"load-as-infoset"-
true- [optional]
Load the document and store only the information defined in the
XML Information Set [XML Information set].
This will force the following features to false:
namespace-declarations,
validate-if-schema,
create-entity-ref-nodes,
create-entity-nodes,
create-cdata-nodes.
This will force the following features to true:
datatype-normalization,
whitespace-in-element-content, comments,
charset-overrides-xml-encoding.
Other features are not changed unless explicity specified in the
description of the features.
Note that querying this feature with getFeature will
return true only if the individual features specified
above are appropriately set.
false- Setting
load-as-infoset to false has
no effect.
"supported-mediatypes-only"-
true- [optional]
Check that the media type of the parsed resource is a supported
media type and call the error handler if an unsupported media type
is encountered. The media types defined in [RFC3023] must
be accepted.
false- [required] (default)
Don't check the media type, accept any type of data.
IDL Definition-
interface DOMBuilder {
attribute DOMEntityResolver entityResolver;
attribute DOMErrorHandler errorHandler;
attribute DOMBuilderFilter filter;
void setFeature(in DOMString name,
in boolean state)
raises(DOMException);
boolean canSetFeature(in DOMString name,
in boolean state);
boolean getFeature(in DOMString name)
raises(DOMException);
Document parseURI(in DOMString uri)
raises(DOMSystemException);
Document parse(in DOMInputSource is)
raises(DOMSystemException);
// ACTION_TYPES
const unsigned short ACTION_REPLACE = 1;
const unsigned short ACTION_APPEND = 2;
const unsigned short ACTION_INSERT_AFTER = 3;
const unsigned short ACTION_INSERT_BEFORE = 4;
void parseWithContext(in DOMInputSource is,
in Node cnode,
in unsigned short action)
raises(DOMException);
};
- Definition group ACTION_TYPES
-
A set of possible actions for the parseWithContext
method.
- Defined Constants
-
ACTION_APPEND- Append the result of parsing the input source to the context
node. For this action to work, the context node must be an
Element.
ACTION_INSERT_AFTER- Insert the result of parsing the input source after the context
node. For this action to work the context nodes parent must be an
Element.
ACTION_INSERT_BEFORE- Insert the result of parsing the input source before the
context node. For this action to work the context nodes parent must
be an
Element.
ACTION_REPLACE- Replace the context node with the result of parsing the input
source. For this action to work the context node must be an
Element, Text, CDATASection,
Comment, ProcessingInstruction, or
EntityReference node.
- Attributes
-
entityResolver of type
DOMEntityResolver- If a
DOMEntityResolver
has been specified, each time a reference to an external entity is
encountered the DOMBuilder will pass the public and
system IDs to the entity resolver, which can then specify the
actual source of the entity.
errorHandler of type
DOMErrorHandler- In the event that an error is encountered in the XML document
being parsed, the
DOMDcoumentBuilder will call back to
the errorHandler with the error information. When the
document loading process calls the error handler the node closest
to where the error occured is passed to the error handler if the
implementation, if the implementation is unable to pass the node
where the error occures the document Node is passed to the error
handler. Mutations to the document from within an error handler
will result in implementation dependent behavour.
filter of type DOMBuilderFilter- When the application provides a filter, the parser will call
out to the filter at the completion of the construction of each
Element node. The filter implementation can choose to
remove the element from the document being constructed (unless the
element is the document element) or to terminate the parse early.
If the document is being validated when it's loaded the validation
happens before the filter is called.
- Methods
-
canSetFeature-
Query whether setting a feature to a specific
value is supported.
The feature name has the same form as a DOM hasFeature string.
Parameters
name of type
DOMString- The feature name, which is a DOM has-feature style
string.
state of type
boolean- The requested state of the feature (
true or
false).
Return Value
|
boolean
|
true if the feature could be successfully set to
the specified value, or false if the feature is not
recognized or the requested value is not supported. The value of
the feature itself is not changed.
|
No Exceptions
getFeature-
Look up the value of a feature.
The feature name has the same form as a DOM hasFeature string
Parameters
name of type
DOMString- The feature name, which is a string with DOM has-feature
syntax.
Return Value
|
boolean
|
The current state of the feature (true or
false).
|
Exceptions
|
DOMException
|
Raise a NOT_FOUND_ERR When the DOMBuilder does not
recognize the feature name.
|
parse-
Parse an XML document from a resource
identified by an
DOMInputSource.
Return Value
|
Document
|
If the DOMBuilder is a synchronous
DOMBuilder the newly created and populated
Document is returned. If the DOMBuilder
is asynchronous then null is returned since the
document object is not yet parsed when this method returns.
|
Exceptions
|
DOMSystemException
|
Exceptions raised by parse originate with the
installed ErrorHandler, and thus depend on the implementation of
the DOMErrorHandler interfaces. The default
ErrorHandlers will raise a DOMSystemException if any
form I/O or other system error occurs during the parse, but
application defined ErrorHandlers are not required to do so.
|
parseURI-
Parse an XML document from a location
identified by an URI reference [
RFC2396]. If the URI contains a
fragment identifier (see section 4.1 in [
RFC2396]), the
behavior is not defined by this specification.
Parameters
uri of type
DOMString- The location of the XML document to be read.
Return Value
|
Document
|
If the DOMBuilder is a synchronous
DOMBuilder the newly created and populated
Document is returned. If the DOMBuilder
is asynchronous then null is returned since the
document object is not yet parsed when this method returns.
|
Exceptions
|
DOMSystemException
|
Exceptions raised by parseURI originate with the
installed ErrorHandler, and thus depend on the implementation of
the DOMErrorHandler interfaces. The default error
handlers will raise a DOMSystemException if any form I/O or other
system error occurs during the parse, but application defined error
handlers are not required to do so.
|
parseWithContext-
Parse an XML document or fragment from a
resource identified by an
DOMInputSource
and insert the content into an existing document at the position
epcified with the
contextNode and
action
arguments. When parsing the input stream the context node is used
for resolving unbound namespace prefixes.
Parameters
is of type DOMInputSource- The
DOMInputSource
from which the source document is to be read.
cnode of type
Node- The
Node that is used as the context for the data
that is being parsed.
action of type
unsigned short- This parameter describes which action should be taken between
the new set of node being inserted and the existing children of the
context node. The set of possible actions is defined above.
Exceptions
|
DOMException
|
HIERARCHY_REQUEST_ERR: Thrown if this action results in an
invalid hierarchy (i.e. a Document with more than one document
element).
|
No Return Value
setFeature-
Set the state of a feature.
The feature name has the same form as a DOM hasFeature
string.
It is possible for a
DOMBuilder to recognize a feature
name but to be unable to set its value.
Parameters
name of type
DOMString- The feature name.
state of type
boolean- The requested state of the feature (
true or
false).
Exceptions
|
DOMException
|
Raise a NOT_SUPPORTED_ERR exception when the
DOMBuilder recognizes the feature name but cannot set
the requested value.
Raise a NOT_FOUND_ERR When the DOMBuilder does not
recognize the feature name.
|
No Return Value
- Interface DOMWriter
-
DOMWriter provides an API for serializing (writing) a DOM
document out in an XML document. The XML data is written to an
output stream, the type of which depends on the specific language
bindings in use. During serialization of XML data, namespace fixup
is done when possible.
DOMWriter accepts any node type for serialization.
For nodes of type Document or Entity,
well formed XML will be created if possible. The serialized output
for these node types is either as a Document or an External Entity,
respectively, and is acceptable input for an XML parser. For all
other types of nodes the serialized form is not specified, but
should be something useful to a human for debugging or diagnostic
purposes. Note: rigorously designing an external (source) form for
stand-alone node types that don't already have one defined in [XML] seems
a bit much to take on here.
Within a Document or Entity being serialized, Nodes are
processed as follows
- Documents are written including an XML declaration and a DTD
subset, if one exists in the DOM. Writing a document node
serializes the entire document.
- Entity nodes, when written directly by
writeNode
defined in the DOMWriter interface, output the entity
expansion but no namespace fixup is done. The resulting output will
be valid as an external entity.
- Entity References nodes are serializes 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 can not be
represented in the specified output encoding are handled according
to the "split-cdata-sections" feature.
If the feature is 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 feature is false, unrepresentable characters
in a CDATA section are reported as errors. The error is not
recoverable - there is no mechanism for supplying alternative
characters and continuing with the serialization.
- All other node types (Element, Text, etc.) are serialized to
their corresponding XML source form.
Within the character data of a document (outside of markup), any
characters that cannot be represented directly are replaced with
character references. Occurrences of '<' and '&' are
replaced by the predefined entities < and &. The
other predefined entities (>, &apos, etc.) are not used;
these characters can be included directly. Any character that can
not be represented directly in the output character encoding is
serialized as a numeric character reference.
Attributes not containing quotes are serialized in quotes.
Attributes containing quotes but no apostrophes are serialized in
apostrophes (single quotes). Attributes containing both forms of
quotes are serialized in quotes, with quotes within the value
represented by the predefined entity ". Any character that
can not be represented directly in the output character encoding is
serialized as a numeric character reference.
Within markup, but outside of attributes, any occurrence of a
character that cannot be represented in the output character
encoding is reported as an error. An example would be serializing
the element <LaCañada/> with the
encoding="us-ascii".
When requested by setting the normalize-characters
feature on DOMWriter, all data to be serialized, both
markup and character data, is W3C Text normalized according to the
rules defined in [CharModel]. The W3C Text
normalization process affects only the data as it is being written;
it does not alter the DOM's view of the document after
serialization has completed.
Namespaces are fixed up during serialization, the serialization
process will verify that namespace declarations, namespace prefixes
and the namespace URIs associated with Elements and Attributes are
consistent. If inconsistencies are found, the serialized form of
the document will be altered to remove them. The algorithm used for
doing the namespace fixup while seralizing a document is a
combination of the algorithms used for lookupNamespaceURI and
lookupNamespacePrefix .
(ED: previous paragraph to be
defined closer here.)
Any changes made affect only the namespace prefixes and
declarations appearing in the serialized data. The DOM's view of
the document is not altered by the serialization operation, and
does not reflect any changes made to namespace declarations or
prefixes in the serialized output.
While serializing a document the serializer will write out
non-specified values (such as attributes whose
specified is false) if the
output-default-values feature is set to
true. If the output-default-values flag
is set to false and the
use-abstract-schema feature is set to
true the abstract schema will be used to determine if
a value is specified or not, if use-abstract-schema is
not set the specified flag on attribute nodes is used
to determine if attribute values should be written out.
Ref to Core spec (1.1.9, XML namespaces, 5th paragraph) entity
ref description about warning about unbound entity refs. Entity
refs are always serialized as &foo;, also mention this in the
load part of this spec.
When serializing a document the DOMWriter checks to see if the
document element in the document is a DOM Level 1 element or a DOM
Level 2 (or higher) element (this check is done by looking at the
localName of the root element). If the root element is a DOM Level
1 element then the DOMWriter will issue an error if a DOM Level 2
(or higher) element is found while serializing. Likewise if the
document element is a DOM Level 2 (or higher) element and the
DOMWriter sees a DOM Level 1 element an error is issued. Mixing DOM
Level 1 elements with DOM Level 2 (or higher) is not supported.
DOMWriters have a number of named features that can
be queried or set. The name of DOMWriter features must
be valid XML names. Implementation specific features (extensions)
should choose an implementation dependent prefix to avoid name
collisions.
Here is a list of properties that must be recognized by all
implementations.
"normalize-characters"-
true- [optional] (default)
Perform the W3C Text Normalization of the characters [CharModel] in
document as they are written out. Only the characters being written
are (potentially) altered. The DOM document itself is
unchanged.
false- [required]
do not perform character normalization.
"split-cdata-sections"-
true- [required] (default)
Split CDATA sections containing the CDATA section termination
marker ']]>' or characters that can not be represented in the
output encoding, and output the characters using numeric character
references. If a CDATA section is split a warning is issued.
false- [required]
Signal an error if a CDATASection contains an
unrepresentable character.
"validation"-
true- [optional]
Use the abstract schema to validate the document as it is being
serialized. If validation errors are found the error handler is
notified about the error. Setting this state will also set the
feature use-abstract-schema to true.
false- [required] (default)
Don't validate the document as it is being serialized.
"expand-entity-references"-
true- [optional]
Expand EntityReference nodes when serializing.
false- [required] (default)
Serialize all EntityReference nodes as XML entity
references.
"whitespace-in-element-content"-
true- [required] (default)
Output all white spaces in the document.
false- [optional]
Only output white space that is not within element content. The
implementation is expected to use the
isWhitespaceInElementContent flag on Text
nodes to determine if a text node should be written out or
not.
"discard-default-content"-
true- [required] (default)
Use whatever information available to the implementation (i.e. XML
schema, DTD, the specified flag on Attr
nodes, and so on) to decide what attributes and content should be
serialized or not. Note that the specified flag on
Attr nodes in itself is not always reliable, it is
only reliable when it is set to false since the only
case where it can be set to false is if the attribute
was created by a Level 1 implementation.
false- [required]
Output all attributes and all content.
"format-canonical"-
true- [optional]
This formatting writes the document according to the rules
specified in [Canonical XML]. Setting this feature to
true will set the feature "format-pretty-print" to false.
false- [required] (default)
Don't canonicalize the output.
"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. Setting
this feature to true will set the feature "format-canonical" to
false.
false- [required] (default)
Don't pretty-print the result.
IDL Definition-
interface DOMWriter {
void setFeature(in DOMString name,
in boolean state)
raises(DOMException);
boolean canSetFeature(in DOMString name,
in boolean state);
boolean getFeature(in DOMString name)
raises(DOMException);
attribute DOMString encoding;
readonly attribute DOMString lastEncoding;
attribute DOMString newLine;
attribute DOMErrorHandler errorHandler;
boolean writeNode(in DOMOutputStream destination,
in Node wnode)
raises(DOMSystemException);
DOMString writeToString(in Node wnode)
raises(DOMException);
};
- Attributes
-
encoding of type
DOMString- The character encoding in which the output will be
written.
The encoding to use when writing is determined as follows:
- If the encoding attribute has been set, that value will be
used.
- If the encoding attribute is
null or empty, but
the item to be written includes an encoding declaration, that value
will be used.
- If neither of the above provides an encoding name, a default
encoding of "UTF-8" will be used.
The default value is null.
errorHandler of type
DOMErrorHandler- The error handler that will receive error notifications during
serialization. The node where the error occured is passed to this
error handler, any modification to nodes from within an error
callback should be avoided since this will result in undefined,
implementation dependent behavior.
lastEncoding of type
DOMString, readonly- The actual character encoding that was last used by this
formatter. This convenience method allows the encoding that was
used when serializing a document to be directly obtained.
newLine of type
DOMString- The end-of-line sequence of characters to be used in the XML
being written out. The only permitted values are these:
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 [XML] 2.11
"End-of-Line Handling".
- 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
-
canSetFeature-
Query whether setting a feature to a specific
value is supported.
The feature name has the same form as a DOM hasFeature string.
Parameters
name of type
DOMString- The feature name, which is a DOM has-feature style
string.
state of type
boolean- The requested state of the feature (
true or
false).
Return Value
|
boolean
|
true if the feature could be successfully set to
the specified value, or false if the feature is not
recognized or the requested value is not supported. The value of
the feature itself is not changed.
|
No Exceptions
getFeature-
Look up the value of a feature.
The feature name has the same form as a DOM hasFeature string
Parameters
name of type
DOMString- The feature name, which is a string with DOM has-feature
syntax.
Return Value
|
boolean
|
The current state of the feature (true or
false).
|
Exceptions
|
DOMException
|
Raise a NOT_FOUND_ERR When the DOMWriter does not
recognize the feature name.
|
setFeature-
Set the state of a feature.
The feature name has the same form as a DOM hasFeature
string.
It is possible for a
DOMWriter to recognize a feature
name but to be unable to set its value.
Parameters
name of type
DOMString- The feature name.
state of type
boolean- The requested state of the feature (
true or
false).
Exceptions
|
DOMException
|
Raise a NOT_SUPPORTED_ERR exception when the
DOMWriter recognizes the feature name but cannot set
the requested value.
Raise a NOT_FOUND_ERR When the DOMWriter does not
recognize the feature name.
|
No Return Value
writeNode-
Write out the specified node as described above
in the description of
DOMWriter. Writing a Document or
Entity node produces a serialized form that is well formed XML.
Writing other node types produces a fragment of text in a form that
is not fully defined by this document, but that should be useful to
a human for debugging or diagnostic purposes.
Parameters
destination of type
DOMOutputStream- The destination for the data to be written.
wnode of type
Node- The
Document or Entity node to be
written. For other node types, something sensible should be
written, but the exact serialized form is not specified.
Return Value
|
boolean
|
Returns true if node was successfully
serialized and false in case a failure occured and the
failure wasn't canceled by the error handler.
|
Exceptions
|
DOMSystemException
|
This exception will be raised in response to any sort of IO or
system error that occurs while writing to the destination. It may
wrap an underlying system exception.
|
writeToString-
Serialize the specified node as described above
in the description of
DOMWriter. The result of
serializing the node is returned as a string. Writing a Document or
Entity node produces a serialized form that is well formed XML.
Writing other node types produces a fragment of text in a form that
is not fully defined by this document, but that should be useful to
a human for debugging or diagnostic purposes.
Parameters
wnode of type
Node- The node to be written.
Return Value
|
DOMString
|
Returns the serialized data, or null in case a
failure occured and the failure wasn't canceled by the error
handler.
|
Exceptions
|
DOMException
|
DOMSTRING_SIZE_ERR: The resulting string is too long to fit in a
DOMString.
|
- Interface DOMInputSource
-
This interface represents a single input source for an XML
entity.
This interface allows an application to encapsulate information
about an input source in a single object, which may include a
public identifier, a system identifier, a byte stream (possibly
with a specified encoding), and/or a character stream.
The exact definitions of a byte stream and a character stream
are binding dependent.
There are two places that the application will deliver this
input source to the parser: as the argument to the
parse method, or as the return value of the DOMEntityResolver.resolveEntity
method.
The DOMBuilder
will use the DOMInputSource object to determine how to
read XML input. If there is a character stream available, the
parser will read that stream directly; if not, the parser will use
a byte stream, if available; if neither a character stream nor a
byte stream is available, the parser will attempt to open a URI
connection to the resource identified by the system identifier.
An DOMInputSource object belongs to the
application: the parser shall never modify it in any way (it may
modify a copy if necessary).
Note: Eventhough all attributes in this interface are
writable the DOM implementation is expected to never mutate a
DOMInputSource.
IDL Definition-
interface DOMInputSource {
attribute DOMInputSource byteStream;
attribute DOMReader characterStream;
attribute DOMString stringData;
attribute DOMString encoding;
attribute DOMString publicId;
attribute DOMString systemId;
attribute DOMString baseURI;
};
- Attributes
-
baseURI of type
DOMString- The base URI to be used (see section 5.1.4 in [RFC2396]) for
resolving relative URIs to absolute URIs. If the baseURI is itself
a relative URI, the behavior is implementation dependent.
byteStream of type DOMInputSource- An attribute of a language-binding dependent type that
represents a stream of bytes.
The parser will ignore this if there is also a character stream
specified, but it will use a byte stream in preference to opening a
URI connection itself.
If the application knows the character encoding of the byte stream,
it should set the encoding property. Setting the encoding in this
way will override any encoding specified in the XML declaration
itself.
characterStream
of type DOMReader- An attribute of a language-binding dependent type that
represents a stream of 16-bit units.
Application must encode the stream using UTF-16 (defined in [Unicode
3.0] and Amendment 1 of [ISO/IEC 10646]).
If a character stream is specified, the parser will ignore any byte
stream and will not attempt to open a URI connection to the system
identifier.
encoding of type
DOMString- The character encoding, if known. The encoding must be a string
acceptable for an XML encoding declaration ([XML] section
4.3.3 "Character Encoding in Entities").
This attribute has no effect when the application provides a
character stream. For other sources of input, an encoding specified
by means of this attribute will override any encoding specified in
the XML claration or the Text Declaration, or an encoding obtained
from a higher level protocol, such as HTTP [RFC2616].
publicId of type
DOMString- The public identifier for this input source. The public
identifier is always optional: if the application writer includes
one, it will be provided as part of the location information.
stringData of type
DOMString- A string attribute that represents a sequence of 16 bit units
(utf-16 encoded characters).
If string data is available in the input source, the parser will
ignore the character stream and the byte stream and will not
attempt to open a URI connection to the system identifier.
systemId of type
DOMString- The system identifier, a URI reference [RFC2396], for
this input source. The system identifier is optional if there is a
byte stream or a character stream, but it is still useful to
provide one, since the application can use it to resolve relative
URIs and can include it in error messages and warnings (the parser
will attempt to fetch the ressource identifier by the URI reference
only if there is no byte stream or character stream
specified).
If the application knows the character encoding of the object
pointed to by the system identifier, it can register the encoding
by setting the encoding attribute.
If the system ID is a relative URI reference (see section 5 in [RFC2396]), the behavior is
implementation dependent.
- Interface LSLoadEvent
-
This interface represents a load event object that signals the
completion of a document load.
IDL Definition-
interface LSLoadEvent : events::Event {
readonly attribute Document newDocument;
readonly attribute DOMInputSource inputSource;
};
- Attributes
-
inputSource of type DOMInputSource,
readonly- The input source that was parsed.
newDocument of type
Document, readonly- The document that finished loading.
- Interface LSProgressEvent
-
This interface represents a progress event object that notifies
the application about progress as a document is parsed. This event
is optional and the rate at which this event is fired is
implementation dependent.
IDL Definition-
interface LSProgressEvent : events::Event {
readonly attribute DOMInputSource inputSource;
readonly attribute unsigned long position;
readonly attribute unsigned long totalSize;
};
- Attributes
-
inputSource of type
DOMInputSource,
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 DOMEntityResolver
-
DOMEntityResolver Provides a way for applications
to redirect references to external entities.
Applications needing to implement customized handling for
external entities must implement this interface and register their
implementation by setting the entityResolver property
of the DOMBuilder.
The DOMBuilder
will then allow the application to intercept any external entities
(including the external DTD subset and external parameter entities)
before including them.
Many DOM applications will not need to implement this interface,
but it will be especially useful for applications that build XML
documents from databases or other specialized input sources, or for
applications that use URI types other than URIs.
Note: DOMEtityResolver is based on the SAX2
[SAX]
EntityResolver interface.
IDL Definition-
interface DOMEntityResolver {
DOMInputSource resolveEntity(in DOMString publicId,
in DOMString systemId,
in DOMString baseURI)
raises(DOMSystemException);
};
- Methods
-
resolveEntity-
Allow the application to resolve external
entities.
The
DOMBuilder
will call this method before opening any external entity except the
top-level document entity (including the external DTD subset,
external entities referenced within the DTD, and external entities
referenced within the document element); the application may
request that the
DOMBuilder
resolve the entity itself, that it use an alternative URI, or that
it use an entirely different input source.
Application writers can use this method to redirect external system
identifiers to secure and/or local URIs, 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
DOMBuilder
must resolve it fully before reporting it to the application
through this interface.
(ED: See issue #4. An
alternative would be to pass the URI out without resolving it, and
to provide a base as an additional parameter. SAX resolves URIs
first, and does not provide a base. )
Parameters
publicId of type
DOMString- The public identifier of the external entity being referenced,
or
null if none was supplied.
systemId of type
DOMString- The system identifier, a URI reference [RFC2396], of
the external entity being referenced exactly as written in the
source (i.e. .
baseURI of type
DOMString- The URI reference representing the base URI of the resource
being parsed, or
null if there is no base URI.
Return Value
|
DOMInputSource
|
A DOMInputSource
object describing the new input source, or null to
request that the parser open a regular URI connection to the system
identifier.
|
Exceptions
|
DOMSystemException
|
Any DOMSystemException, possibly wrapping another
exception.
|
- Interface DOMBuilderFilter
-
DOMBuilderFilters provide applications the ability
to examine nodes as they are being constructed during a parse. As
each node is examined, it may be modified or removed, or the entire
parse may be terminated early.
At the time any of the filter methods are called by the parser,
the owner Document and DOMImplementation objects exist and are
accessible. The document element is never passed to the
DOMBuilderFilter methods, i.e. it is not possible to
filter out the document element.
All validity checking while reading a document occurs on the
source document as it appears on the input stream, not on the DOM
document as it is built in memory. With filters, the document in
memory may be a subset of the document on the stream, and its
validity may have been affected by the filtering.
(ED: The description of these
methods is not complete)
IDL Definition-
interface DOMBuilderFilter {
unsigned long startNode(in Node snode);
unsigned long endNode(in Node enode);
readonly attribute unsigned long whatToShow;
};
- Attributes
-
whatToShow of type
unsigned long, readonly- Tells the
DOMBuilder
what types of nodes to show to the filter. See
NodeFilter for definition of the constants. The
constant SHOW_ATTRIBUTE is meaningless here, attribute
nodes will never be passed to a
DOMBuilderFilter.
- Methods
-
endNode-
This method will be called by the parser at the
completion of the parse of each node. The node will exist and be
complete, as will all of its children, and their children,
recursively. The parent node will also exist, although that node
may be incomplete, as 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. This
node may also be removed from its parent node, which will prevent
it from appearing in the final document at the completion of the
parse. Aside from this one operation on the node's parent, the
state of the rest of the document outside of this node is not
defined, and the affect of any attempt to navigate to or 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.
Parameters
enode 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 long
|
ACCEPT if this Node should be
included in the DOM document being built.REJECT if the Node and all of its
children should be rejected.
|
No Exceptions
startNode-
This method will be called by the parser 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
startNode function.
The element node passed to
startNode 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
startNode filter function may access or change the
attributers 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
snode of type
Node- The newly encountered element. At the time this method is
called, the element is incomplete - it will have its attributes,
but no children.
- Issue startNode-1:
- Should the parameter be an Element since we only passed
elements to startNode?
Return Value
|
unsigned long
|
ACCEPT if this Element should be
included in the DOM document being built.REJECT if the Element and all of its
children should be rejected.SKIP if the Element should be
rejected. All of its children are inserted in place of the rejected
Element node.
|
No Exceptions
- Interface DOMWriterFilter
-
DOMWriterFilters provide applications the ability
to examine nodes as they are being serialized.
DOMWriterFilter lets the application decide what nodes
should be serialized or not.
IDL Definition-
interface DOMWriterFilter : traversal::NodeFilter {
readonly attribute unsigned long whatToShow;
};
- Attributes
-
whatToShow of type
unsigned long, readonly- Tells the
DOMWriter
what types of nodes to show to the filter. See
NodeFilter for definition of the constants. The
constant SHOW_ATTRIBUTE is meaningless here, attribute
nodes will never be passed to a DOMWriterFilter.
- Interface DocumentLS
-
The DocumentLS interface provides a mechanism by which the
content of a document can be replaced with the DOM tree produced
when loading a URI, or parsing a string. The expectation is that an
instance of the DocumentLS interface can be obtained by using
binding-specific casting methods on an instance of the Document
interface.
uses the default features.
IDL Definition-
interface DocumentLS {
attribute boolean async;
void abort();
boolean load(in DOMString uri);
boolean loadXML(in DOMString source);
DOMString saveXML(in Node snode)
raises(DOMException);
};
- Attributes
-
async of type
boolean- Indicates whether the method load should be synchronous or
asynchronous. When the async attribute is set to
true
the load method returns control to the caller before the document
has completed loading. The default value of this property is
false.
Setting the value of this attribute might throw NOT_SUPPORTED_ERR
if the implementation doesn't support the mode the attribute is
being set to.
- Issue async-1:
- Should the DOM spec define the default value of this property?
What if implementing both async and sync IO is impractical in some
systems?
Resolution: 2001-09-14. default is false but we
need to check with Mozilla and IE.
- Methods
-
abort-
If the document is currently being loaded as a
result of the method
load being invoked the loading
and parsing is immediately aborted. The possibly partial result of
parsing the document is discarded and the document is cleared.
No Parameters
No Return Value
No Exceptions
load-
Replaces the content of the document with the
result of parsing the given URI. Invoking this method will either
block the caller or return to the caller immediately depending on
the value of the async attribute. Once the document is fully loaded
the document will fire a "load" event that the caller can register
as a listener for. If an error occurs the document will fire an
"error" event so that the caller knows that the load failed (see
ParseErrorEvent).
Parameters
uri of type
DOMString- The URI reference for the XML file to be loaded. If this is a
relative URI...
Return Value
|
boolean
|
If async is set to true load returns
true if the document load was successfully initiated.
If an error occurred when initiating the document load
load returns false.
If async is set to false load returns
true if the document was successfully loaded and
parsed. If an error occurred when either loading or parsing the URI
load returns false.
|
No Exceptions
loadXML-
Replace the content of the document with the
result of parsing the input string, this method is always
synchronous.
Parameters
source of type
DOMString- A string containing an XML document.
Return Value
|
boolean
|
true if parsing the input string succeeded without
errors, otherwise false.
|
No Exceptions
saveXML-
Save the document or the given node to a string
(i.e. serialize the document or node).
Parameters
snode of type
Node- Specifies what to serialize, if this parameter is
null the whole document is serialized, if it's
non-null the given node is serialized.
Return Value
|
DOMString
|
The serialized document or null.
|
Exceptions
|
DOMException
|
WRONG_DOCUMENT_ERR: Raised if the node passed in as the node
parameter is from an other document.
|
- Interface ParseErrorEvent
-
ParseErrorEvent is the event that is fired if there's an error
in the XML document being parsed.
IDL Definition-
interface ParseErrorEvent : events::Event {
readonly attribute DOMError error;
};
- Attributes
-
error of type
DOMError, readonly- An non-zero implementation dependent error code describing the
error, or
0 if there is no error.