Most visited

Recently visited

Results for

Added in API level 8

LSSerializer

public interface LSSerializer

org.w3c.dom.ls.LSSerializer

LSSerializer提供了一个用于将DOM文档序列化（写入）为XML的API。 XML数据被写入字符串或输出流。 序列化过程中所做的任何更改或修正只会影响序列化的数据。 序列化操作决不会更改Document对象及其子项。

在XML数据序列化过程中，命名空间修复按照附录B [ DOM Level 3 Core ]中的定义完成。[ DOM Level 2 Core ]允许将空字符串作为真实的命名空间URI。 如果namespaceURI的Node为空字符串，则序列化将它们视为null ，忽略前缀（如果有）。

LSSerializer接受任何用于序列化的节点类型。 对于类型为Document或Entity节点，尽可能创建格式良好的XML（如果文档或实体来自解析操作并且自创建之后保持不变，则保证格式良好）。 这些节点类型的序列化输出分别作为XML文档或外部XML实体，并且是XML解析器的可接受输入。 对于所有其他类型的节点，序列化形式是与实现相关的。

内的 Document ， DocumentFragment ，或 Entity被序列化， Nodes进行如下处理

注意： Node的序列化并不总是生成格式良好的XML文档，即 LSParser在解析结果序列化时可能会引发致命错误。

在文档的字符数据中（标记之外），不能直接表示的任何字符都将替换为字符引用。 “<”和“＆”的出现由预定义的实体＆lt; 和＆amp ;. 其他预定义实体（＆gt ;,'和'）可能不被使用，除非需要（例如，在诸如']]>'的情况下使用＆gt ;. 在输出字符编码中不能直接表示的任何字符都被序列化为数字字符引用（并且由于字符编码标准通常使用字符的十六进制表示，因此鼓励在序列化字符引用时使用十六进制表示形式）。

要允许属性值包含单引号和双引号，撇号或单引号字符（'）可以表示为“'”，双引号字符（“）as”“”。在输出字符编码的属性值中不能直接表示的其他字符将被序列化为数字字符引用。

在标记中但在属性之外，任何不能用输出字符编码表示的字符都会报告为DOMError致命错误。 一个例子是序列化元素<LaCa？ada />与encoding="us-ascii" 。 这将导致生成DOMError “wf-invalid-character-in-node-name”（如“ well-formed ”中所建议的）。

当通过将LSSerializer上的参数“ normalize-characters ” LSSerializer为真时，根据[ XML 1.1 ]附录E中fully normalized字符的定义，对要序列化的所有数据（标记和字符数据）执行字符标准化。 字符规范化过程只影响正在写入的数据; 在序列化完成后，它不会更改DOM的文档视图。

实现需要支持编码“UTF-8”，“UTF-16”，“UTF-16BE”和“UTF-16LE”，以确保数据在需要所有XML解析器支持的所有编码中可序列化。 当编码是UTF-8时，不管字节顺序标记是否被序列化，或者输出是大端还是小端，都取决于实现。 当编码为UTF-16时，无论输出是大端还是小端，都依赖于实现，但必须为非字符输出（如LSOutput.byteStream或LSOutput.systemId生成字节顺序标记。 如果未生成字节顺序标记，则会报告“需要字节顺序标记”的警告。 当编码为UTF-16LE或UTF-16BE时，输出为big-endian（UTF-16BE）或little-endian（UTF-16LE），并且不会生成字节顺序标记。 在所有情况下，编码声明（如果生成）都将对应于序列化过程中使用的编码（例如，如果请求UTF-16，将显示encoding="UTF-16" ）。

命名空间在序列化过程中被修复，序列化过程将验证命名空间声明，命名空间前缀和与元素和属性关联的命名空间URI是否一致。 如果发现不一致，则会更改文档的序列化格式以将其删除。 序列化文档时用于执行名称空间修复的方法是[ DOM Level 3 Core ]的附录B.1“名称空间规范化”中定义的算法。

在序列化文档时，参数“discard-default-content”控制是否序列化非指定的数据。

在序列化时，错误和警告通过错误处理程序（ LSSerializer.domConfig的“ error-handler ”参数）报告给应用程序。 本规范绝不会尝试定义序列化DOM节点时可能发生的所有可能的错误和警告，但会定义一些常见的错误和警告情况。 本规范定义的错误和警告类型（ DOMError.type ）为：

"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.

除了提出定义的错误和警告之外，实现还应该针对任何其他错误和警告情况（如IO错误（文件未找到，权限被拒绝，等等））引发实现特定的错误和警告。

另请参阅 Document Object Model (DOM) Level 3 Load and Save Specification 。

Summary

Public methods
abstract DOMConfiguration getDomConfig()

所述 DOMConfiguration使用由对象 LSSerializer序列化DOM节点时。
abstract String getNewLine()

要写出的XML中使用的行尾字符序列。
abstract void setNewLine(String newLine)

要写出的XML中使用的行尾字符序列。
abstract boolean write(Node nodeArg, LSOutput destination)

按照上述 LSSerializer接口的一般描述序列化指定的节点。
abstract String writeToString(Node nodeArg)

按照上述 LSSerializer接口的一般描述序列化指定的节点。
abstract boolean writeToURI(Node nodeArg, String uri)

一种方便的方法，就像调用 LSSerializer.write时调用了 LSOutput而没有指定编码，而 LSOutput.systemId设置为 uri参数。

Public methods

getDomConfig

Added in API level 8 
DOMConfiguration getDomConfig ()

所述DOMConfiguration使用由对象LSSerializer序列化DOM节点时。
除了[ DOM Level 3 Core ]中定义的DOMConfiguration接口识别的参数外， LSSerializer的DOMConfiguration对象LSSerializer添加或修改了以下参数：

"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).

Returns
DOMConfiguration

getNewLine

Added in API level 8 
String getNewLine ()

要写出的XML中使用的行尾字符序列。 任何字符串都受支持，但XML仅将一组字符序列视为行尾（请参见[ XML 1.0 ]中的第2.11节“行尾处理”），如果序列化内容为XML 1.0或2.11节，如果序列化内容是XML 1.1，则在[ XML 1.1 ]中的“行尾处理”）。 使用除推荐的字符序列以外的其他字符序列可能导致文档不可序列化或格式不正确）。
在检索时，此属性的默认值是实现特定的默认行尾序列。 DOM实现应该选择默认值以匹配正在使用的环境中的文本文件的常规约定。 实现必须根据序列化的内容选择一个匹配XML 1.0或XML 1.1所允许的序列的默认序列。 将此属性设置为null将重置其值为默认值。

Returns
String

setNewLine

Added in API level 8 
void setNewLine (String newLine)

要写出的XML中使用的行尾字符序列。 任何字符串都受支持，但XML仅将一组字符序列视为行结束符 （如果序列化内容是XML 1.0或2.11节，请参见[ XML 1.0 ]中的第2.11节“行结束处理”如果序列化的内容是XML 1.1，则在[ XML 1.1 ]中的“行尾处理”）。 使用除推荐的字符序列以外的其他字符序列可能导致文档不可序列化或格式不正确）。
在检索时，此属性的默认值是实现特定的默认行尾序列。 DOM实现应该选择默认值以匹配正在使用的环境中的文本文件的常规约定。 实现必须根据序列化的内容选择一个匹配XML 1.0或XML 1.1所允许的序列的默认序列。 将此属性设置为null将重置其值为默认值。

Parameters
newLine String

write

Added in API level 8 
boolean write (Node nodeArg, 
                LSOutput destination)

按照上述LSSerializer接口的一般描述序列化指定的节点。 输出写入提供的LSOutput 。
在写入LSOutput ，通过查看通过LSOutput和要写入的项目（或其所有者文档）可按以下顺序访问的编码信息来查找编码：

  1. LSOutput.encoding,
  2. Document.inputEncoding,
  3. Document.xmlEncoding.

If no encoding is reachable through the above properties, a default encoding of "UTF-8" will be used. If the specified encoding is not supported an "unsupported-encoding" fatal error is raised.
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 Node: The node to serialize.
destination LSOutput: The destination for the serialized DOM.
Returns
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.
Throws
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

Added in API level 8 
String writeToString (Node nodeArg)

按照上述LSSerializer接口的一般描述序列化指定的节点。 输出被写入返回给调用者的DOMString 。 使用的编码是DOMString类型的编码，即UTF-16。 请注意，在DOMString对象中不会生成字节顺序标记。

Parameters
nodeArg Node: The node to serialize.
Returns
String Returns the serialized data.
Throws
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

Added in API level 8 
boolean writeToURI (Node nodeArg, 
                String uri)

一种方便的方法，就好像 LSSerializer.write被调用 LSOutput而没有指定编码，而 LSOutput.systemId设置为 uri参数。

Parameters
nodeArg Node: The node to serialize.
uri String: The URI to write to.
Returns
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.
Throws
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.
Android开发手册

Hooray!