org.w3c.dom.ls
接口 LSSerializer

public interface LSSerializer

LSSerializer 提供了将 DOM 文档序列化（编写）为 XML 的 API。XML 数据被写入字符串或输入流。在序列化期间所做的任何更改或修复仅影响序列化的数据。Document 对象及其子对象永远不会被序列化操作所改变。

在序列化 XML 数据期间，将像在 [DOM Level 3 Core] 的附录 B 中所定义的那样，执行名称空间修复。[DOM Level 2 Core] 允许空字符串作为实际名称空间 URI。如果一个 Node 的 namespaceURI 是空字符串，则序列化将把它们视为 null，从而忽略前缀（如果有）。

LSSerializer 接受任何用于序列化的节点类型。对于 Document 或 Entity 类型的节点，将在可能的情况下创建格式良好的 XML（如果文档或实体来自解析操作并且自创建以来没有改变，则可保证格式良好性）。这些节点类型的序列化输出分别作为 XML 文档或外部 XML 实体，并且是 XML 解析器可接受的输入。对于所有其他类型的节点，序列化格式是依赖于实现的。

在被序列化的 Document、DocumentFragment 或 Entity 内，将按如下方式处理 Nodes

• 编写 Document 节点，包括 XML 声明（除非参数 "xml-declaration" 设置为 false）和 DTD 子集（如果 DOM 中存在一个）。编写 Document 节点序列化整个文档。
• 当 Entity 节点直接由 LSSerializer.write 编写时将输出实体扩展，但不执行名称空间修复。得到的输出将作为有效的外部实体。
• 如果参数 "entities" 设置为 true，则把 EntityReference 节点序列化为输出中形式 " &entityName;" 的实体引用。将忽略实体引用的子节点（扩展）。如果参数 "entities" 设置为 false，则仅序列化实体引用的子项。将始终序列化不带有子项的 EntityReference 节点（没有相应的 Entity 节点，或者相应的 Entity 节点没有子节点）。
• CDATAsections 包括不能用指定的输出编码表示的内容字符，将根据 "split-cdata-sections" 参数对其进行处理。如果将该参数设置为 true，则将拆分 CDATAsections，将不可表示的字符序列化为普通内容中的数字字符引用。不指定拆分的精确位置和数量。如果参数设置为 false，则参数 "well-formed" 设置为 true 时，CDATAsection 中不可表示的字符将报告为 "wf-invalid-character" 错误。该错误不可恢复 - 没有提供替换字符和继续进行序列化的机制。
• DocumentFragment 节点可通过按照文档片段的子片段在文档片段中出现的顺序序列化这些子片段得以序列化。
• 所有其他节点类型（Element、Text 等）都将序列化为其相应的 XML 源格式。

注：序列化 Node 并不总能生成格式良好的 XML 文档，即解析得到的序列化时 LSParser 可能会抛出严重错误。

在文档的字符数据中（在标记之外），任何无法直接表示的字符都将替换为字符引用。'<' 和 '&' 将由预定义实体 < 和 & 替换。除非必需（例如在 ']]>' 这一情况下使用 >），否则不能使用其他预定义实体（>、' 和 "）。无法用输入字符编码直接表示的任何字符都将序列化为数值字符引用（由于字符编码标准一般使用字符的十六进制表示形式，所以在序列化字符引用时鼓励使用十六进制表示形式）。

若要允许属性值同时包括单引号和双引号，可以将省略号或单引号字符 (') 表示为 "'"，双引号字符 (") 表示为 """。无法直接用输出字符编码表示的新行字符和其他字符将被序列化为数值字符引用。

在标记内（但在属性外），无法用输出字符编码表示的任何字符都将被报告为 DOMError 严重错误。其中的一个示例就是使用 encoding="us-ascii" 序列化元素 <LaCa?ada/>。这将导致生成 DOMError "wf-invalid-character-in-node-name"（在 "well-formed" 中建议的）。

当通过将 LSSerializer 上的参数 "normalize-characters" 设置为 true 请求字符标准化时，对所有被序列化的数据（包括标识和字符数据），将根据对 "fully normalized" 字符（包括在 [XML 1.1] 的附录 E 中）的定义实施字符标准化。字符标准化过程只影响正在编写的数据；在序列化完成之后不会改变 DOM 的文档视图。

需要实现支持编码 "UTF-8"、"UTF-16"、"UTF-16BE" 和 "UTF-16LE"，以保证数据在需要得到所有 XML 解析器支持的所有编码中能够序列化。当编码是 UTF-8 时，无论字节顺序标记是否得到了序列化，无论输出是大尾端还是 小尾端，都具有实现依赖性。当编码是 UTF-16 时，无论输出是大尾端还是小尾端，都具有实现依赖性，但必须为非字符输出（如 LSOutput.byteStream 或 LSOutput.systemId）生成字节顺序标记。如果未生成字节顺序标记，则报告一个 "byte-order-mark-needed" 警告。当编码是 UTF-16LE 或 UTF-16BE 时，输出是大尾端 (UTF-16BE) 或小尾端 (UTF-16LE)，将不生成字节顺序标记。在所有这些情况下，编码声明（如果已生成）将与序列化期间使用的编码一致（例如，如果请求 UTF-16，则 encoding="UTF-16" 将出现）。

名称空间将在序列化期间进行修复，序列化过程将检验名称空间声明、名称空间前缀以及与元素和属性相关的名称空间 URI 是否一致。如果发现有不一致，则将改变文档的序列化形式以删除它们。序列化文档时修复名称空间所使用的方法是在 [DOM Level 3 Core] 的附录 B.1 "Namespace normalization" 中定义的算法。

在序列化文档期间，参数 "discard-default-content" 控制是否序列化非指定数据。

在序列化期间，将通过错误处理程序（LSSerializer.domConfig 的 "error-handler" 参数）将错误和警告报告给应用程序。此规范从不尝试定义序列化 DOM 节点期间可能发生的所有错误和警告，但却对一些常见的错误和警告情形做了定义。此规范定义的错误和警告类型 (DOMError.type) 包括：

"no-output-specified" [fatal]

当未在 LSOutput 中指定输出的情况下向 LSOutput 写入时，将引发此错误。

"unbound-prefix-in-entity-reference" [fatal]

引发此错误的情况是：配置参数 "namespaces" 设置为 true，并且在没有名称空间前缀绑定的位置引用了其替换文本包含未绑定的名称空间前缀的实体。

"unsupported-encoding" [fatal]

如果遇到了不受支持的编码，则引发此错误。

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

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

方法摘要

DOMConfiguration	getDomConfig() 在序列化 DOM 节点时由 LSSerializer 使用的 DOMConfiguration 对象。
LSSerializerFilter	getFilter() 当应用程序提供过滤器时，在序列化每个节点前串行器先调出过滤器。
String	getNewLine() 在所写出的 XML 中使用的字符的行尾序列。
void	setFilter(LSSerializerFilter filter) 当应用程序提供过滤器时，在序列化每个节点前串行器将先调出过滤器。
void	setNewLine(String newLine) 在所写出的 XML 中使用的字符的行尾序列。
boolean	write(Node nodeArg, LSOutput destination) 像前面对 LSSerializer 接口的一般介绍中所描述的那样序列化指定的节点。
String	writeToString(Node nodeArg) 像前面对 LSSerializer 接口的一般介绍中所描述的那样序列化指定的节点。
boolean	writeToURI(Node nodeArg, String uri) 这是一种简便方法，其作用就像使用没有指定编码的 LSOutput 调用 LSSerializer.write，并且 LSOutput.systemId 被设置为 uri 参数。

方法详细信息

getDomConfig

DOMConfiguration getDomConfig()

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

"canonical-form"

true

[可选] 根据在 [Canonical XML] 中指定的规则编写文档。除 "canonical-form》、[DOM Level 3 Core] 中描述的行为外，将此参数设置为 true 将把参数 "format-pretty-print"、"discard-default-content" 和 "xml-declaration " 设置为 false。将其中的一个参数设置为 true 将把此参数设置为 false。当 "canonical-form" 为 true 时序列化 XML 1.1 文档将生成严重错误。

false。

[必需]（默认）不规范化输出。

"discard-default-content"

true

[必需]（默认）使用 Attr.specified 属性来决定必须丢弃哪些属性。注意，有些实现可能使用任何可供实现使用的信息（即 XML 模式、DTD、Attr.specified 属性等）来决定在此参数设置为 true 时应丢弃哪些属性和内容。

false。

[必需] 保留所有属性和所有内容。

"format-pretty-print"

true

[可选] 通过添加空白格式化输出，以产生打印美观的、缩排的、可为人读的格式。转换的准确形式不是由此规范指定的。打印美观性可改变文档的内容，并且会影响文档的有效性，验证实现必须保留有效性。

false。

[必需]（默认）不打印美观化结果。

"ignore-unknown-character-denormalizations"

true

[必需]（默认），如果在 [XML 1.1] 受支持的情况下检查完全标准化时遇到了不能为其确定标准化属性的字符，则将引发一个 "unknown-character-denormalization" 警告（而不是像未设置此参数那样引发错误），并将忽略由这些字符引起的任何可能的反向标准化。

false。

[可选] 如果遇到了处理器不能为其确定标准化属性的字符，则将引发严重错误。

"normalize-characters"

此参数与 [DOM Level 3 Core] 中的 DOMConfiguration 定义的参数等效。与在 Core 中不同，此参数的默认值是 true。尽管根据 [XML 1.1] 中的附录 E 的规定，不需要 DOM 实现支持完全标准化文档中的字符，但如果支持，则默认情况下必须激活此参数。

"xml-declaration"

true

[必需]（默认）如果 Document、Element 或 Entity 节点被序列化，则必须包括 XML 声明或文本声明。版本（如果文档是 Level 3 文档并且版本为非 null，则使用 Document.xmlVersion，否则使用值 "1.0"）和输出编码（关于如何查找输出编码的详细信息请参见 LSSerializer.write ）在已序列化的 XML 声明中指定。

false。

[必需] 不序列化 XML 和文本声明。如果这会引起问题（即已序列化的数据是 XML 版本，而不是 [XML 1.0]，或者必须有编码才能重新解析序列化的数据），则将发出一个 "xml-declaration-needed" 警告。

getNewLine

String getNewLine()

在所写出的 XML 中使用的字符的行尾序列。任何字符都受支持，但 XML 仅将某些字符集序列视为行尾（如果序列化的内容是 XML 1.0，则请参见 [XML 1.0] 中的 2.11 节 "End-of-Line Handling"，如果序列化的内容是 XML 1.1，则请参见 [XML 1.1] 中的 2.11 节 "End-of-Line Handling"）。使用其他字符序列而不是推荐的字符序列会导致文档要么不能序列化，要么不是格式良好的文档。）
检索时，此属性的默认值特定于实现的默认行尾序列。DOM 实现应该选择默认值，以符合所用环境中文本文件的常规约定。实现必须选择与 XML 1.0 或 XML 1.1 所允许的序列匹配的默认序列，具体情况取决于序列化的内容。将此属性设置为 null 将把其值重置为默认值。

setNewLine

void setNewLine(String newLine)

在所写出的 XML 中使用的字符的行尾序列。任何字符都受支持，但 XML 仅将某些字符集序列视为行尾（如果序列化的内容是 XML 1.0，则请参见 [XML 1.0] 中的 2.11 节 "End-of-Line Handling"，如果序列化的内容是 XML 1.1，则请参见 [XML 1.1] 中的 2.11 节 "End-of-Line Handling"）。使用其他字符序列而不是推荐的字符序列会导致文档要么不能序列化，要么不是格式良好的文档。）
检索时，此属性的默认值是特定于实现的默认行尾序列。DOM 实现必须选择默认值，以符合所用环境中文本文件的常规约定。实现必须选择与 XML 1.0 或 XML 1.1 所允许的序列匹配的默认序列，具体情况取决于序列化的内容。将此属性设置为 null 将把其值重置为默认值。

getFilter

LSSerializerFilter getFilter()

当应用程序提供过滤器时，在序列化每个节点前串行器先调出过滤器。过滤器实现可以选择从流中删除节点，或者提前终止序列化。
过滤器将在使用了 DOMConfiguration 参数请求的操作后调用。例如，如果把 "cdata-sections" 设置为 false，则不会将 CDATA 节传递给过滤器。

setFilter

void setFilter(LSSerializerFilter filter)

当应用程序提供过滤器时，在序列化每个节点前串行器将先调出过滤器。过滤器实现可以选择从流中删除节点，或者提前终止序列化。
过滤器将在使用了 DOMConfiguration 参数请求的操作后调用。例如，如果把 "cdata-sections" 设置为 false，则不会将 CDATA 节传递给过滤器。

write

boolean write(Node nodeArg,
              LSOutput destination)
              throws LSException

像前面对 LSSerializer 接口的一般介绍中所描述的那样序列化指定的节点。将输出写入所提供的 LSOutput。
当向 LSOutput 写入时，编码可以通过查找可通过 LSOutput 获得的编码信息和按如下顺序编写的条目（或者其所有者文档）来发现：

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

如果没有编码可通过上述属性获得，则将使用 "UTF-8" 的默认编码。如果指定的编码不受支持，则将引发 "unsupported-encoding" 严重错误。
如果在 LSOutput 中未指定输出，则将引发 "no-output-specified" 严重错误。
实现负责将适当的媒体类型与已序列化的数据相关联。
当向 HTTP URI 写入时，将执行 HTTP PUT。当向其他类型的 URI 写入时，向 URI 写入数据的机制具有实现依赖性。

参数：

nodeArg - 将序列化的节点。

destination - 已序列化 DOM 的目标。

返回：

如果 node 被成功序列化，则返回 true。如果常规处理停止，但实现仍在序列化文档，则返回 false；序列化的结果是具有实现依赖性。

抛出：

LSException - SERIALIZE_ERR:如果 LSSerializer 不能序列化节点，则引发此异常。如果 DOM 应用程序想获得有关错误的详细信息，则它必须附加上使用参数 "error-handler" 的 DOMErrorHandler。

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
                   throws LSException

这是一种简便方法，其作用就像使用没有指定编码的 LSOutput 调用 LSSerializer.write，并且 LSOutput.systemId 被设置为 uri 参数。

参数：

nodeArg - 要序列化的节点。

uri - 要写入到的 URI。

返回：

如果 node 被成功序列化，则返回 true。如果常规处理停止，但实现仍在序列化文档，则返回 false；序列化的结果是具有实现依赖性。

抛出：

LSException - SERIALIZE_ERR:如果 LSSerializer 无法序列化节点，则引发此异常。如果 DOM 应用程序想获得有关错误的详细信息，则它必须附加上使用参数 "error-handler" 的 DOMErrorHandler。

writeToString

String writeToString(Node nodeArg)
                     throws DOMException,
                            LSException

像前面对 LSSerializer 接口的一般介绍中所描述的那样序列化指定的节点。将输出写入到返回给调用者的 DOMString。所使用的编码是 DOMString 类型的编码，即 UTF-16。注意，在 DOMString 对象中未生成字节顺序标记。

参数：

nodeArg - 将序列化的节点。

返回：

返回序列化的数据。

抛出：

DOMException - DOMSTRING_SIZE_ERR: 如果得到的字符串太长，不能放在 DOMString 中，则将引发此异常。

LSException - SERIALIZE_ERR: 如果 LSSerializer 不能序列化节点，则引发此异常。如果 DOM 应用程序想获得有关错误的详细信息，则它必须附加上使用参数 "error-handler" 的 DOMErrorHandler。