+ 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, readonly-
+
true if the LSParser is asynchronous,
+ false if it is synchronous.
+
+
+
+busy of type boolean, readonly-
+
true if the LSParser is currently
+ busy loading a document, otherwise false.
+
+
+
+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.characterStream
+
+-
+
+
LSInput.byteStream
+
+-
+
+
LSInput.stringData
+
+-
+
+
LSInput.systemId
+
+-
+
+
LSInput.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.characterStream
+
+-
+
+
LSOutput.byteStream
+
+-
+
+
LSOutput.systemId
+
+
+
+
+ LSOutput objects belong to the application. The
+ DOM implementation will never modify them (though it may make
+ copies and modify the copies, if necessary).
+
+
+
IDL Definition-
+
+
+
+- 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].
+
+
+
+
