Module java.xml

软件包 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直接写入时，输出实体扩展，但没有命名空间LSSerializer.write完成。 所产生的输出将作为外部实体有效。
• 如果参数“ entities ”设置为true ，则EntityReference节点在输出中被序列化为“ &entityName; ”形式的实体引用。 子节点（扩展）的实体引用将被忽略。 如果参数“ entities ”设置为false ，则仅实体引用的子项被序列化。 EntityReference无子节点（无对应Entity节点或对应的Entity节点无子节点）始终序列化。
• 包含不能在指定输出编码中表示的内容字符的CDATAsections根据“ split-cdata-sections ”参数进行处理。 如果参数设置为true ，则CDATAsections被拆分，并且CDATAsections代表的字符在普通内容中被串行化为数字字符引用。 没有指定分割的确切位置和数量。 如果参数设置为false ，在不可表示的字符CDATAsection被报告为"wf-invalid-character"错误，如果参数“ well-formed ”设置为true 。 该错误是无法恢复的 - 没有提供替代字符和继续序列化的机制。
• DocumentFragment节点通过序列化文档片段的儿童，他们出现在文档片段的顺序序列化。
• 所有其他节点类型（元素，文本等）都被序列化为相应的XML源表单。

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

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

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

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

当通过将LSSerializer上的参数“ normalize-characters ” LSSerializer为true时，根据[ 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]

如果在LSOutput没有指定输出，则在LSOutput 。

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

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

"unsupported-encoding" [fatal]

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

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

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

从以下版本开始：

1.5

方法摘要

Modifier and Type	方法	描述
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接口的一般说明中所述将指定的节点序列化。
String	writeToString(Node nodeArg)	按照 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"警告（而不是引发错误，如果此参数未设置）并忽略由这些字符引起的任何可能的非规范化。

false

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

"normalize-characters"

该参数等同于[ DOM Level 3 Core ]中由DOMConfiguration定义的参数。 与Core不同，此参数的默认值为true 。 尽管根据[ XML 1.1 ]附录E，DOM实现不需要支持文档中的字符，但如果支持，则必须默认激活该参数。

"xml-declaration"

true

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

false

[ 必需 ]不要序列化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只将某一组字符序列作为行尾（如果序列化内容是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参数所请求的操作之后调用过滤器。 例如，如果“ 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的目的地。

结果

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

异常

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

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
            throws LSException

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

参数

nodeArg - 要序列化的节点。

uri - 要写入的URI。

结果

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

异常

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

writeToString

String writeToString(Node nodeArg)
              throws DOMException,
                     LSException

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

参数

nodeArg - 要序列化的节点。

结果

返回序列化数据。

异常

DOMException - DOMSTRING_SIZE_ERR：如果生成的字符串太长 DOMString适合 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.