The interfaces within this section are considered fundamental,
and must be fully implemented by all conforming implementations of
the DOM Load and Save module.
- Exception LSException
-
Parser or write operations may throw an LSException if the
processing is stopped. The processing can be stopped due to a
DOMError with a severity of
DOMError.SEVERITY_FATAL_ERROR or a non recovered
DOMError.SEVERITY_ERROR, or if
DOMErrorHandler.handleError() returned
false.
Note: As suggested in the definition of the constants in
the DOMError interface, a DOM implementation may
choose to continue after a fatal error, but the resulting DOM tree
is then implementation dependent.
IDL Definition-
- Definition group LSExceptionCode
-
An integer indicating the type of error generated.
- Defined Constants
-
PARSE_ERR- If an attempt was made to load a document, or an XML Fragment,
using
LSParser
and the processing has been stopped.
SERIALIZE_ERR- If an attempt was made to serialize a
Node using
LSSerializer
and the processing has been stopped.
- 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 [DOM Level 3
Core], by using the method
DOMImplementation.getFeature with parameter values
"LS" (or "LS-Async") and
"3.0" (respectively).
IDL Definition-
- Definition group DOMImplementationLSMode
-
Integer parser mode constants.
- Defined Constants
-
MODE_ASYNCHRONOUS- Create an asynchronous
LSParser.
MODE_SYNCHRONOUS- Create a synchronous
LSParser.
- Methods
-
createLSInput-
createLSOutput-
createLSParser-
Create a new
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
LSParser that is
created will operate in synchronous mode, if it's
MODE_ASYNCHRONOUS then the LSParser that is created
will operate in asynchronous mode.
schemaType of type
DOMString- An absolute URI representing the type of the schema language used during the load of a
Document using the newly created LSParser. Note that no
lexical checking is done on the absolute URI. In order to create a
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 [XML Schema Part
1], applications must use the value
"http://www.w3.org/2001/XMLSchema". For XML DTD
[XML
1.0], applications must use the value
"http://www.w3.org/TR/REC-xml". Other Schema languages
are outside the scope of the W3C and therefore should recommend an
absolute URI in order to use this method.
Return Value
|
LSParser
|
The newly created LSParser object. This
LSParser is either
synchronous or asynchronous depending on the value of the
mode argument.
Note: By default, the newly created LSParser does not
contain a 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
LSParser object contains
a reference to the default error handler.
|
Exceptions
|
DOMException
|
NOT_SUPPORTED_ERR: Raised if the requested mode or schema type
is not supported.
|
createLSSerializer-
Create a new
LSSerializer object.
Return Value
|
LSSerializer
|
The newly created LSSerializer
object.
Note: By default, the newly created 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
LSSerializer object
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
DOMImplementationLS.createLSParser()
method.
As specified in [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 XML
1.0 normalized value. However, if the parameters
"
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 parameters "
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
[XML
Information Set].
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 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-dependent. 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. 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 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 (LSParser.domConfig's
"
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:
"check-character-normalization-failure"
[error]- Raised if the parameter "
check-character-normalization" is set to true and a
string is encountered that fails normalization checking.
"doctype-not-allowed" [fatal]- Raised if the configuration parameter "disallow-doctype" is
set to
true and a doctype is encountered.
"no-input-specified" [fatal]- Raised when loading a document and no input is specified in the
LSInput
object.
"pi-base-uri-not-preserved" [warning]- Raised if a processing instruction is encountered 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 "
entities" is set to false and the
following XML file is parsed:
<!DOCTYPE root [
<!ENTITY e SYSTEM 'subdir/myentity.ent'
]>
<root>
&e;
</root>
And subdir/myentity.ent contains:
<one>
<two/>
</one>
<?pi 3.14159?>
<more/>
"unbound-prefix-in-entity" [warning]- An implementation dependent warning that may be raised if the
configuration parameter "
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.
"unknown-character-denormalization" [fatal]- Raised if the configuration parameter "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 "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-
- 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, readonlytrue if the LSParser is asynchronous,
false if it is synchronous.
busy of type
boolean, readonlytrue if the LSParser is currently
busy loading a document, otherwise false.
domConfig of type
DOMConfiguration, readonly- The
DOMConfiguration object used when parsing an
input source. This DOMConfiguration is specific to the
parse operation. 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 on the
DOMConfiguration interface defined in [DOM Level 3
Core], the DOMConfiguration objects for
LSParser add or modify the following parameters:
"charset-overrides-xml-encoding"-
true- [optional] (default)
If a higher level protocol such as HTTP [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
[XML
1.0]). Explicitly setting an encoding in the 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 [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 [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 [DOM Level 3
Core], this parameter will default to true
for LSParser.
"namespaces"-
true- [required] (default)
Perform the namespace processing as defined in [XML
Namespaces] and [XML Namespaces 1.1].
false- [optional]
Do not perform the namespace processing.
"resource-resolver"- [required]
A reference to a 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
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 [IETF RFC 3023] must always be
accepted.
false- [required] (default)
Accept any media type.
"validate"- See the definition of
DOMConfiguration for a
description of this parameter. Unlike in [DOM Level 3
Core], the processing of the internal subset is always
accomplished, even if this parameter is set to
false.
"validate-if-schema"- See the definition of
DOMConfiguration for a
description of this parameter. Unlike in [DOM Level 3
Core], the processing of the internal subset is always
accomplished, even if this parameter is set to
false.
"well-formed"- See the definition of
DOMConfiguration for a
description of this parameter. Unlike in [DOM Level 3
Core], this parameter cannot be set to
false.
filter of type 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 "
validate" is set to true, the validation
is done before invoking the filter.
- 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
LSInput.
Parameters
input of type LSInput- The
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
LSParser.busy
attribute is true.
|
|
LSException
|
PARSE_ERR: Raised if the LSParser was unable to
load the XML document. DOM applications should attach a
DOMErrorHandler using the parameter "
error-handler" if they wish to get details on the
error.
|
parseURI-
Parse an XML document from a location
identified by a URI reference [
IETF RFC 2396]. If the URI
contains a fragment identifier (see section 4.1 in [
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, or null if an error
occured. 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.busy
attribute is true.
|
|
LSException
|
PARSE_ERR: Raised if the LSParser was unable to
load the XML document. DOM applications should attach a
DOMErrorHandler using the parameter "
error-handler" if they wish to get details on the
error.
|
parseWithContext-
Parse an XML fragment from a resource
identified by a
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,
inputEncoding,
xmlStandalone, and all other such attributes are set
to what they would be set to if the input source was parsed using
LSParser.parse().
This method is always synchronous, even if the
LSParser is asynchronous (
LSParser.async is
true).
If an error occurs while parsing, the caller is notified through
the
ErrorHandler instance associated with the
"
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: "
validate", "
validate-if-schema", and "
element-content-whitespace". Other parameters will be
treated normally, and the parser is expected to call the
LSParserFilter just
as if a whole document was parsed.
Parameters
input of type LSInput- The
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
|
HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be
inserted before, after, or as a child of the context node (see also
Node.insertBefore or Node.replaceChild in
[DOM
Level 3 Core]).
NOT_SUPPORTED_ERR: Raised if the LSParser doesn't
support this method, or if the context node is of type
Document and the DOM implementation doesn't support
the replacement of the DocumentType child or
Element child.
NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a
read only node and the
content is being appended to its child list, or if the parent node
of the context node is read
only node and the content is being inserted in its child
list.
INVALID_STATE_ERR: Raised if the LSParser.busy
attribute is true.
|
|
LSException
|
PARSE_ERR: Raised if the LSParser was unable to
load the XML fragment. DOM applications should attach a
DOMErrorHandler using the parameter "
error-handler" if they wish to get details on the
error.
|
- 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 DOMImplementationLS.createLSInput()
to create objects that implement this interface.
The LSParser
will use the LSInput object to determine how to read
data. The 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:
LSInput.characterStreamLSInput.byteStreamLSInput.stringDataLSInput.systemIdLSInput.publicId
If all inputs are null, the LSParser will report a
DOMError with its DOMError.type set to
"no-input-specified" and its
DOMError.severity set to
DOMError.SEVERITY_FATAL_ERROR.
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-
- Attributes
-
baseURI of type
DOMString- The base URI to be used (see section 5.1.4 in [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
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 [XML 1.1]) when parsing
[XML
1.1].
characterStream
of type 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 16-bit
units. The application must encode the stream using UTF-16
(defined in [Unicode] and in [ISO/IEC
10646]). It is not a requirement to have an XML
declaration when using character streams. If an XML declaration is
present, the value of the encoding attribute will be
ignored.
encoding of type
DOMString- The character encoding, if known. The encoding must be a string
acceptable for an XML encoding declaration ([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
[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 16-bit
units (UTF-16 encoded characters). It is not a requirement to
have an XML declaration when using
stringData. If an
XML declaration is present, the value of the encoding attribute
will be ignored.
systemId of type
DOMString- The system identifier, a URI reference [IETF RFC
2396], for this input source. The system identifier is
optional if there is a byte stream, a character stream, or string
data. 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 LSParser will only attempt to fetch the
resource identified by the URI reference 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 specified system ID is a relative URI reference (see section
5 in [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 "resource-resolver" parameter of
DOMConfiguration objects attached to LSParser and LSSerializer. It can
also be register on DOMConfiguration objects attached
to Document if the "LS" feature is supported.
The LSParser
will then allow the application to intercept any external entities,
including the external DTD subset and external parameter entities,
before including them. The top-level document entity is never
passed to the resolveResource method.
Many DOM applications will not need to implement this interface,
but it will be especially useful for applications that build XML
documents from databases or other specialized input sources, or for
applications that use URNs.
Note: LSResourceResolver is based on the
SAX2 [SAX] EntityResolver
interface.
IDL Definition-
- Methods
-
resolveResource-
Allow the application to resolve external
resources.
The
LSParser will
call this method before opening any external resource, including
the external DTD subset, external entities referenced within the
DTD, and external entities referenced within the document element
(however, the top-level document entity is not passed to this
method). The application may then request that the
LSParser
resolve the external 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, 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).
Parameters
type of type
DOMString- The type of the resource being resolved. For XML
[XML
1.0] resources (i.e. entities), applications must use
the value
"http://www.w3.org/TR/REC-xml". For XML
Schema [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, e.g. the target
namespace of the XML Schema [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 [IETF RFC
2396], of the external resource being referenced, or
null if no system identifier was supplied.
baseURI of type
DOMString- The absolute base URI of the resource being parsed, or
null if there is no base URI.
Return Value
|
LSInput
|
A LSInput object describing
the new input source, or null to request that the
parser open a regular URI connection to the resource.
|
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. The child
nodes of an EntityReference node are passed to the
filter if the parameter "
entities" is set to false. Note that, as
described by the parameter "
entities", unexpanded entity reference nodes are never
discarded and are always passed to 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.
DOM applications must not raise exceptions in a filter. The
effect of throwing exceptions from a filter is DOM implementation
dependent.
IDL Definition-
- 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
LSParser what types of
nodes to show to the method LSParserFilter.acceptNode.
If a node is not shown to the filter using this attribute, it is
automatically included in the DOM document being built. 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 LSParserFilter.acceptNode.
The constants used here are defined in [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
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.FILTER_SKIP if the Element should be
skipped. All of its children are inserted in place of the skipped
Element 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
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 [DOM Level 3
Events].
The units used for the attributes position and
totalSize are not specified and can be implementation
and input dependent.
IDL Definition-
- Attributes
-
input of type
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. A value of
0 is returned if the total size cannot be determined
or estimated.
- Interface LSLoadEvent
-
This interface represents a load event object that signals the
completion of a document load.
IDL Definition-
- Attributes
-
input of type 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. Any changes or fixups made during the
serialization affect only the serialized data. The
Document object and its children are never altered by
the serialization operation.
During serialization of XML data, namespace fixup is done as
defined in [DOM Level 3 Core], Appendix B.
[DOM
Level 2 Core] allows empty strings as a real namespace
URI. If the namespaceURI of a Node is
empty string, the serialization will treat them as
null, ignoring the prefix if any.
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 "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 LSSerializer.write,
outputs the entity expansion but no namespace fixup is done. The
resulting output will be valid as an external entity.- If the parameter "
entities" is set to
true,
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. If the parameter "
entities" is set to false, only the
children of the entity reference are serialized.
EntityReference nodes with no children (no
corresponding Entity node or the corresponding
Entity nodes have no children) are always
serialized.
CDATAsections containing content characters that
cannot be represented in the specified output encoding are handled
according to the "
split-cdata-sections" parameter.
If the parameter is set to true,
CDATAsections 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 CDATAsection are reported as
"wf-invalid-character" errors if the parameter
"
well-formed" is set to true. 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.
Note: The serialization of a Node does not
always generate a well-formed XML document, i.e. a
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 DOMError fatal error. An
example would be serializing the element <LaCañada/>
with encoding="us-ascii". This will result with a
generation of a DOMError
"wf-invalid-character-in-node-name" (as proposed in "
well-formed").
When requested by setting the parameter "
normalize-characters" on LSSerializer to
true, character normalization is performed according to the
definition of fully
normalized characters included in appendix E of
[XML
1.1] 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.
Implementations are required to support the encodings "UTF-8",
"UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is
serializable in all encodings that are required to be supported by
all XML parsers. When the encoding is UTF-8, whether or not a byte
order mark is serialized, or if the output is big-endian or
little-endian, is implementation dependent. When the encoding is
UTF-16, whether or not the output is big-endian or little-endian is
implementation dependent, but a Byte Order Mark must be generated
for non-character outputs, such as LSOutput.byteStream
or LSOutput.systemId.
If the Byte Order Mark is not generated, a "byte-order-mark-needed"
warning is reported. When the encoding is UTF-16LE or UTF-16BE, the
output is big-endian (UTF-16BE) or little-endian (UTF-16LE) and the
Byte Order Mark is not be generated. In all cases, the encoding
declaration, if generated, will correspond to the encoding used
during the serialization (e.g. encoding="UTF-16" will
appear if UTF-16 was requested).
Namespaces are fixed up during serialization, the serialization
process will verify that namespace declarations, namespace prefixes
and the namespace URI 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
[DOM
Level 3 Core].
While serializing a document, the parameter "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 (LSSerializer.domConfig's
"
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:
"no-output-specified" [fatal]- Raised when writing to a
LSOutput if no output is
specified in the LSOutput.
"unbound-prefix-in-entity-reference" [fatal]- Raised if the configuration parameter "
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.
"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-
- Attributes
-
domConfig of type
DOMConfiguration, readonly- The
DOMConfiguration object used by the
LSSerializer when serializing a DOM node.
In addition to the parameters recognized by the
DOMConfiguration interface defined in [DOM Level 3
Core], the DOMConfiguration objects for
LSSerializer adds, or modifies, the following
parameters:
"canonical-form"-
true- [optional]
Writes the document according to the rules specified in
[Canonical XML]. In addition to the
behavior described in "
canonical-form" [DOM Level 3 Core], setting
this parameter to true will set the parameters
"format-pretty-print",
"discard-default-content",
and "xml-declaration", to
false. Setting one of those parameters to
true will set this parameter to false.
Serializing an XML 1.1 document when "canonical-form" is
true will generate a fatal error.
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.
false- [required] (default)
Don't pretty-print the result.
-
"ignore-unknown-character-denormalizations"
-
true- [required] (default)
If, while verifying full normalization when [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.
false- [optional]
Report a 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 [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
appendix E of [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 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
[XML
1.0], or an encoding would be needed to be able to
re-parse the serialized data).
filter of
type 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 after the operations requested by the
DOMConfiguration parameters have been applied. For
example, CDATA sections won't be passed to the filter if "
cdata-sections" is set to
false.
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 XML treats only a
certain set of characters sequence as end-of-line (See section
2.11, "End-of-Line Handling" in [XML 1.0], if the serialized
content is XML 1.0 or section 2.11, "End-of-Line Handling" in
[XML
1.1], if the serialized content is XML 1.1). Using other
character sequences than the recommended ones can result in a
document that is either not serializable or not well-formed).
On retrieval, the default value of this attribute is the
implementation specific 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 1.0 or XML 1.1, depending on the serialized
content. Setting this attribute to null will reset its
value to the default value.
- Methods
-
write-
Serialize the specified node as described above
in the general description of the
LSSerializer
interface. The output is written to the supplied
LSOutput.
When writing to a
LSOutput, the encoding is
found by looking at the encoding information that is reachable
through the
LSOutput and the item to
be written (or its owner document) in this order:
LSOutput.encoding,Document.inputEncoding,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.
If no output is specified in the
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
LSOutput- The destination for the serialized DOM.
Return Value
|
boolean
|
Returns true if node was successfully
serialized. Return false in case the normal processing
stopped but the implementation kept serializing the document; the
result of the serialization being implementation dependent
then.
|
Exceptions
|
LSException
|
SERIALIZE_ERR: Raised if the LSSerializer was
unable to serialize the node. DOM applications should attach a
DOMErrorHandler using the parameter "
error-handler" if they wish to get details on the
error.
|
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. The encoding used is the encoding of the
DOMString type, i.e. UTF-16. Note that no Byte Order
Mark is generated in a
DOMString object.
Parameters
nodeArg of type
Node- The node to serialize.
Return Value
|
DOMString
|
Returns the serialized data.
|
Exceptions
|
DOMException
|
DOMSTRING_SIZE_ERR: Raised if the resulting string is too long
to fit in a DOMString.
|
|
LSException
|
SERIALIZE_ERR: Raised if the LSSerializer was
unable to serialize the node. DOM applications should attach a
DOMErrorHandler using the parameter "
error-handler" if they wish to get details on the
error.
|
writeToURI-
A convenience method that acts as if
LSSerializer.write
was called with a
LSOutput with no encoding
specified and
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. Return false in case the normal processing
stopped but the implementation kept serializing the document; the
result of the serialization being implementation dependent
then.
|
Exceptions
|
LSException
|
SERIALIZE_ERR: Raised if the LSSerializer was
unable to serialize the node. DOM applications should attach a
DOMErrorHandler using the parameter "
error-handler" if they wish to get details on the
error.
|
- 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 DOMImplementationLS.createLSOutput()
to create objects that implement this interface.
The LSSerializer will use
the LSOutput object to determine where to serialize
the output to. The 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:
LSOutput.characterStreamLSOutput.byteStreamLSOutput.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-
- Attributes
-
byteStream of type
LSOutputStream- An attribute of a language and binding dependent type that
represents a writable stream of bytes.
characterStream
of type 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 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
([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 [IANA-CHARSETS] should be
referred to using their registered names.
systemId of type
DOMString- The system identifier, a URI reference [IETF RFC
2396], for this output destination.
If the system ID is a relative URI reference (see section 5 in
[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 [DOM Level
2 Traversal and Range].
Document, DocumentType,
DocumentFragment, Notation,
Entity, and children of Attr nodes are
not passed to the filter. The child nodes of an
EntityReference node are only passed to the filter if
the EntityReference node is skipped by the method
LSParserFilter.acceptNode().
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 "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.
DOM applications must not raise exceptions in a filter. The
effect of throwing exceptions from a filter is DOM implementation
dependent.
For efficiency, a node passed to the filter may not be the same
as the one that is actually in the tree. And the actual node (node
object identity) may be reused during the process of filtering and
serializing a document.
IDL Definition-
- Attributes
-
whatToShow
of type unsigned long, readonly- Tells the
LSSerializer what
types of nodes to show to the filter. If a node is not shown to the
filter using this attribute, it is automatically serialized. 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.
Unlike [DOM Level 2 Traversal and
Range], the SHOW_ATTRIBUTE constant
indicates that the Attr nodes are shown and passed to
the filter.
The constants used here are defined in [DOM Level
2 Traversal and Range].