public interface LSSerializer

一个LSSerializer提供了一个API，用于将DOM文档序列化（写入）为XML。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节点会序列化整个文档。
直接由LSSerializer.write写入的Entity节点，输出实体扩展，但不进行命名空间修复。生成的输出将作为外部实体有效。
如果参数"entities"设置为true，则将EntityReference节点序列化为输出中的形式为"&entityName;"的实体引用。实体引用的子节点（扩展）将被忽略。如果参数"entities"设置为false，则仅序列化实体引用的子节点。没有子节点的EntityReference节点（没有对应的Entity节点或对应的Entity节点没有子节点）始终被序列化。
包含无法在指定输出编码中表示的内容字符的CDATAsections根据"split-cdata-sections"参数进行处理。如果参数设置为true，则会拆分CDATAsections，并且无法表示的字符将作为普通内容中的数字字符引用进行序列化。拆分的位置和数量没有指定。如果参数设置为false，则CDATAsection中无法表示的字符将报告为"wf-invalid-character"错误，如果参数"well-formed"设置为true。错误是不可恢复的-没有提供替代字符并继续序列化的机制。
通过序列化文档片段的子节点按照它们在文档片段中出现的顺序对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]字符的定义在要序列化的所有数据上执行字符规范化，包括标记和字符数据。字符规范化过程仅在写入数据时影响数据；它不会在序列化完成后更改文档的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错误（文件未找到、权限被拒绝等）等）引发特定于实现的错误和警告。

另请参阅文档对象模型（DOM）Level 3 Load and Save Specification。

自：: 1.5

Method Summary

Modifier and Type

Method

Description

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和LSOutput.systemId设置为uri参数的LSSerializer.write。

Method Details
- getDomConfig
  
  DOMConfiguration getDomConfig()
  
  LSSerializer 在序列化 DOM 节点时使用的 DOMConfiguration 对象。
  除了 DOMConfiguration 接口中定义的参数外，LSSerializer 的 DOMConfiguration 对象添加或修改了以下参数：
  
  "canonical-form"
  
  true
  
  [可选] 根据 [规范化 XML] 中指定的规则写入文档。除了 "canonical-form" 中描述的行为外，将此参数设置为 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 属性来决定应该丢弃哪些属性。请注意，如果将此参数设置为 true，则一些实现可能会使用实现中可用的任何信息（即 XML 模式、DTD、Attr.specified 属性等）来确定应该丢弃哪些属性和内容。
  
  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。虽然 DOM 实现不需要支持根据 [XML 1.1] 附录 E 中的规范对文档中的字符进行完全规范化，但如果支持，此参数必须默认激活。
  
  "xml-declaration"
  
  true
  
  [必需] (默认) 如果序列化 Document、Element 或 Entity 节点，则应包括 XML 声明或文本声明。版本（如果文档是 Level 3 文档且版本非空，则使用 Document.xmlVersion，否则使用值 "1.0"）和输出编码（有关如何查找输出编码的详细信息，请参阅 LSSerializer.write）在序列化的 XML 声明中指定。
  
  false
  
  [必需] 不序列化 XML 和文本声明。如果这会导致问题（即序列化数据的 XML 版本不是 [XML 1.0]，或者需要编码才能重新解析序列化的数据），则报告 "xml-declaration-needed" 警告。
- getNewLine
  
  String getNewLine()
  
  要在写出的 XML 中使用的换行字符序列。支持任何字符串，但 XML 仅将某些字符序列视为换行符（请参阅 [XML 1.0] 中的第 2.11 节“换行处理”或 [XML 1.1] 中的第 2.11 节“换行处理”）。使用推荐的字符序列之外的其他字符序列可能导致文档无法序列化或无法格式正确。
  在检索时，此属性的默认值是实现特定的默认换行字符序列。DOM 实现应选择与所用环境中文本文件的通常约定相匹配的默认值。实现必须选择与 XML 1.0 或 XML 1.1 允许的字符序列之一匹配的默认序列。将此属性设置为 null 将重置其值为默认值。
- setNewLine
  
  void setNewLine(String newLine)
  
  要在写出的 XML 中使用的换行字符序列。支持任何字符串，但 XML 仅将某些字符序列视为换行符（请参阅 [XML 1.0] 中的第 2.11 节“换行处理”或 [XML 1.1] 中的第 2.11 节“换行处理”）。使用推荐的字符序列之外的其他字符序列可能导致文档无法序列化或无法格式正确。
  在检索时，此属性的默认值是实现特定的默认换行字符序列。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 和要写入的项（或其所有者文档）的编码信息来确定的，顺序如下：
  
  LSOutput.encoding，
  
  Document.inputEncoding，
  
  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 和将 LSOutput.systemId 设置为 uri 参数的 LSSerializer.write。
  
  参数:
  
  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，以获取有关错误的详细信息。

Interface LSSerializer

Method Summary

Method Details

getDomConfig

getNewLine

setNewLine

getFilter

setFilter

write

writeToURI

writeToString