compact2, compact3

org.w3c.dom.ls

Interface LSSerializer

public interface LSSerializer

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

在序列化XML数据期间，按照[ DOM Level 3 Core ]（附录B）中的定义进行命名空间修复。[ DOM Level 2 Core ]允许空字符串作为真实的命名空间URI。 如果一个namespaceURI的Node是空字符串，则序列化将会将它们视为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节点通过按照文档片段中出现的顺序序列化文档片段的子节点进行序列化。
• 所有其他节点类型（元素，文本等）都被序列化为相应的XML源表单。

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

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

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

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

当由参数“设置请求normalize-characters上的” LSSerializer为true时，字符规范化根据定义的执行fully normalized个包括在[附录E.字符XML 1.1上的所有数据]被序列化，无论标记和字符数据。 字符归一化过程仅影响正在写入的数据; 在序列化完成后，它不会更改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），并且不会生成字节顺序标记。 在所有情况下，编码声明，如果产生的，将对应于序列化过程中使用的编码方式（例如， encoding="UTF-16"如果请求UTF-16将出现）。

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

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

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

"no-output-specified" [fatal]

在写入LSOutput如果在LSOutput中未指定输出）时LSOutput 。

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

如果配置参数“ namespaces ”设置为true并且其替换文本包含未绑定的命名空间前缀的实体在名称空间前缀没有绑定的位置中引用，则引发。

"unsupported-encoding" [fatal]

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

除了提出定义的错误和警告之外，预计实施将针对任何其他错误和警告情况（如IO错误（未找到文件，拒绝许可，...等））提出实施特定的错误和警告。

另见Document Object Model (DOM) Level 3 Load and Save Specification 。

方法摘要

Modifier and Type	Method and Description
DOMConfiguration	getDomConfig() DOMConfiguration对象在 LSSerializer时序列化DOM节点。
LSSerializerFilter	getFilter() 当应用程序提供一个过滤器时，序列化程序将在序列化每个节点之前调用过滤器。
String	getNewLine() 要在XML中使用的字符的行尾序列被写出。
void	setFilter(LSSerializerFilter filter) 当应用程序提供一个过滤器时，序列化程序将在序列化每个节点之前调用过滤器。
void	setNewLine(String newLine) 要在XML中使用的字符的行尾序列被写出。
boolean	write(Node nodeArg, LSOutput destination) 按照LSSerializer界面的一般说明，按照上述方式对指定的节点进行 LSSerializer化。
String	writeToString(Node nodeArg) 按照LSSerializer接口的一般说明，按照上述的顺序序列化 LSSerializer节点。
boolean	writeToURI(Node nodeArg, String uri) 充当如果一种简便方法 LSSerializer.write被称为具有 LSOutput没有编码指定和 LSOutput.systemId集到 uri参数。

方法详细信息

getDomConfig

DOMConfiguration getDomConfig()

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

"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"字符，然后引发"unknown-character-denormalization"警告（而不是引发错误，如果此参数未设置）并忽略由这些字符引起的任何可能的非规范化。

false

[ 可选 ]如果遇到处理器无法确定规范化属性的字符，则报告致命错误。

"normalize-characters"

该参数DOMConfiguration于[ DOM Level 3 Core ] DOMConfiguration定义的DOMConfiguration 。 与Core不同，此参数的默认值为true 。 虽然不是必需的DOM的实现，以支持fully normalizing个根据[附录E中的文档中的字符XML 1.1 ]，该参数必须被默认激活如果支持的话。

"xml-declaration"

true

[ 需要 ]（ 默认 ）如果Document ， Element ，或Entity节点被序列化，XML声明，或文本声明，应该包括在内。 版本（ Document.xmlVersion如果文档是3级文档，版本不为空，否则使用值“1.0”），输出编码（参见LSSerializer.write有关如何查找输出编码的详细信息）在序列化XML声明。

false

[ required ]不要序列化XML和文本声明。 报告一个"xml-declaration-needed"警告，如果这将导致问题（即序列化数据是除[ XML 1.0 ]之外的XML版本，或者需要编码才能重新解析序列化数据）。

getNewLine

String getNewLine()

要在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将将其值重置为默认值。

setNewLine

void setNewLine(String newLine)

要在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将将其值重置为默认值。

getFilter

LSSerializerFilter getFilter()

当应用程序提供一个过滤器时，序列化程序将在序列化每个节点之前调用过滤器。 过滤器实现可以选择从流中删除节点或提前终止序列化。
在DOMConfiguration参数所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接口的一般描述中如上所述序列化LSSerializer节点。 输出写入提供的LSOutput 。
当写入LSOutput时，可以通过查看通过LSOutput可以访问的编码LSOutput和要写入的项目（或其所有者文档）按以下顺序找到编码：

1. LSOutput.encoding ，
2. Document.inputEncoding ，
3. Document.xmlEncoding 。

如果通过上述属性无法访问编码，则将使用“UTF-8”的默认编码。 如果不支持指定的编码，则会引发“不支持编码”的致命错误。
如果没有指定输出LSOutput ，“无输出指定的”致命错误引发。
该实现负责将适当的媒体类型与序列化数据相关联。
当写入HTTP URI时，会执行HTTP PUT。 当写入其他类型的URI时，将数据写入URI的机制取决于实现。

参数

nodeArg - 要序列化的节点。

destination - 序列化DOM的目的地。

结果

返回true如果node成功序列化。 返回false ，以防正常处理停止，但实现继续序列化文档; 然后序列化的结果依赖于实现。

异常

LSException - SERIALIZE_ERR：如果LSSerializer无法序列化节点，则引发。 如果DOM应用程序希望获得有关错误的详细信息， DOMErrorHandler使用参数“ error-handler ”附加一个DOMErrorHandler 。

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
            throws LSException

充当如果一种简便方法 LSSerializer.write被称为具有 LSOutput没有编码指定和 LSOutput.systemId集到 uri参数。

参数

nodeArg - 要序列化的节点。

uri - 要写入的URI。

结果

返回true如果node成功序列化。 返回false ，以防正常处理停止，但实现继续序列化文档; 然后序列化的结果依赖于实现。

异常

LSException - SERIALIZE_ERR：如果LSSerializer无法序列化节点，则引发。 如果DOM应用程序希望获取有关错误的详细信息， DOMErrorHandler使用参数“ error-handler ”附加一个DOMErrorHandler 。

writeToString

String writeToString(Node nodeArg)
              throws DOMException,
                     LSException

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

参数

nodeArg - 要序列化的节点。

结果

返回序列化数据。

异常

DOMException - DOMSTRING_SIZE_ERR：如果生成的字符串太长而不适合 DOMString 。

LSException - SERIALIZE_ERR：如果LSSerializer无法序列化节点，则引发。 如果DOM应用程序希望获得有关错误的详细信息， DOMErrorHandler使用参数“ error-handler ”附加DOMErrorHandler 。