compact2, compact3

org.w3c.dom.ls

Interface LSSerializer

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声明”设置为false）和DTD子集，如果存在一个DOM。写一Document节点序列化整个文档。
• Entity节点，当直接写的LSSerializer.write，输出实体扩展但没有命名空间固定完成。由此产生的输出将是有效的作为一个外部实体。
• 如果参数“ entities”设置为true，EntityReference节点序列化为形式的“&entityName;”输出实体引用。实体引用的子节点（扩展）被忽略。如果参数“ entities”设置为false，只有实体参考的儿童系列。EntityReference节点没有孩子（没有相应的Entity节点或相应的Entity节点没有孩子）总是连载。
• CDATAsections包含内容的特点，不能在指定的输出编码表示的是按照“ split-cdata-sections”参数。如果参数设置为true，CDATAsections分裂，并无法代表人物是序列化为普通字符引用内容。未指定拆分的确切位置和数量。如果参数设置为false，在CDATAsection无法代表的人物报道"wf-invalid-character"错误如果参数“ well-formed”设置为true。错误是不可恢复的-没有提供替代字符的机制，并继续序列化。
• DocumentFragment节点被序列化文档片段的孩子们出现在文档片段的顺序。
• 所有其他节点类型（元素、文本等）被序列化到相应的XML数据源的形式。

注：一Node序列化并不总是产生一个结构良好的XML文档，即LSParser可能引发致命的错误，分析产生的序列化。

在文档（标记的外部）的字符数据中，不能直接表示的任何字符都替换为字符引用。“<”和“”的出现被预定义的实体和它所取代；和；。其他预定义实体（>；，&apos；，和"；）可能无法使用，除了在需要的地方（如使用>；例如] ] >”）。任何字符，不能直接输出的字符编码表示序列化为数字字符引用（由于字符编码标准通常使用字符、十六进制表示使用十六进制表示序列化时字符引用是鼓励）。

允许属性值包含单引号和双引号，单引号或单引号字符（“）可以表示为“&apos；”，和双引号（“）为“"；”。新的一行字符和其他字符，不能直接表达的属性值，在输出的字符编码是序列化为一个数字字符的参考。

在标记，但属性之外，出现的任何一个，不能在输出字符编码为代表的人物报道是一个DOMError致命错误。一个例子是序列化元 <艾达> 与 encoding="us-ascii" LACA�/。这将导致一代一 DOMError WF无效字符在节点名称”（如提出“ well-formed”）。

当通过设置参数“ normalize-characters”LSSerializer真正要求的字符归一化是根据fully normalized字符的定义包括在[ XML 1.1 ]所有数据附录E进行序列化执行，标记和字符数据。字符归一化过程只影响数据是书面的；它不序列化之后完成了修改文档的DOM的观点。

实现都必须支持的编码utf-8“UTF-16BE，“UTF-16”、“，和”UTF-16LE”来保证数据在所有编码所需的所有XML解析器支持序列化。当编码是UTF-8，是否一个字节顺序标记序列化，或者如果输出是大端或小端，是依赖于实现的。当编码为UTF-16，是否输出大端或小端是依赖于实现的，而是一个字节顺序标记必须为非字符输出所产生的，如LSOutput.byteStream或LSOutput.systemId。如果没有生成字节顺序标记，则报告一个“字节顺序标记所需的”警告。UTF-16BE UTF-16LE或当编码，输出（UTF-16BE）的大端或小端（UTF-16LE）和字节顺序标记是不会产生。在所有的情况下，编码声明，如果产生，将对应的编码中使用的序列化（如encoding="UTF-16"如果要求是UTF-16出现）。

命名空间是固定在序列化，序列化过程将验证命名空间前缀和命名空间声明，元素和属性关联的命名空间URI是一致的。如果发现有不一致的地方，该文档的序列化形式将修改删除它们。用来做命名空间固定而序列化文件附录B.1定义算法的方法，“命名空间规范”的DOM Level 3 Core ]，[。

当序列化文件，参数“放弃默认内容”控制是否非指定的数据序列化。

序列化时，错误和警告上报申请通过错误处理程序（LSSerializer.domConfig“ error-handler”参数）。本规范并不试图定义所有可能的错误和警告，可以在序列化一个DOM节点发生，但一些常见的错误和警告的情况下被定义。类型（DOMError.type）错误和警告的规范定义：

"no-output-specified" [fatal]

当写一 LSOutput如果没有输出是在 LSOutput指定。

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

提出如果配置参数” namespaces”设置为 true和实体的替代文本包含绑定命名空间前缀是在一个位置，那里是没有绑定引用的命名空间前缀。

"unsupported-encoding" [fatal]

提出如果遇到不支持的编码。

除了提高所定义的错误和警告，实现预期将提高执行特定的错误和警告的任何其他错误和警告的情况下，如输入输出错误（文件未找到，许可被拒绝，…）等。

又见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接口的一般描述。
String	writeToString(Node nodeArg) 将指定的节点如上面所描述的对 LSSerializer接口的一般描述。
boolean	writeToURI(Node nodeArg, String uri) 一个方便的方法，好像 LSSerializer.write被称为一个没有编码指定 LSOutput.systemId设置为 uri争论 LSOutput。

方法详细信息

getDomConfig

DOMConfiguration getDomConfig()

的 DOMConfiguration对象使用的 LSSerializer当序列化一个DOM节点。除了在 DOM Level 3 Core ] [参数定义的 DOMConfiguration界面确认
，为 LSSerializer的 DOMConfiguration对象添加，或修改下列参数：

"canonical-form"

true

[可选]写文件按照指定的规则 Canonical XML ] [。除了行为描述的“ canonical-form”[ DOM Level 3 Core ]，设置参数为 true设定参数”格式漂亮的打印”、“放弃默认内容”和“XML声明”，以 false。设置的参数 true将此参数设置为 false。序列化的XML 1.1文档时的“典型”的形式是 true将产生一个致命的错误。

false

[要求]（默认）不规范的输出。

"discard-default-content"

true

[要求]（默认）使用 Attr.specified属性来决定哪些属性应该被丢弃。请注意，一些实现可能使用任何可用的信息，实施（即XML Schema，DTD的 Attr.specified属性，等等）来确定哪些属性和内容丢弃，如果这个参数设置为 true。

false

【要求】保持所有的属性和所有内容。

"format-pretty-print"

true

[可选]格式化输出中加入空格来产生一个漂亮的印刷，缩进，人类可读的形式。该规范没有指定转换的确切形式。漂亮的打印更改文档的内容，并可能会影响文档的有效性，验证实现应保持有效性。

false

[要求]（默认）不美观打印结果。

"ignore-unknown-character-denormalizations"

true

[要求]（默认）如果，而验证的完全正常化时[ XML 1.1 ]是支持的，一个字符的归一化性质不能确定时，提出一个 "unknown-character-denormalization"警告（而不是提高一个错误，如果没有设置此参数）和忽略任何可能造成denormalizations这些字符。

false

[可选]报告一个致命错误，如果一个字符遇到该处理器不能确定正常化属性。

"normalize-characters"

这个参数是相当于一 DOM Level 3 Core ]的[ DOMConfiguration定义。不同的核心，该参数的缺省值是 true。而DOM实现不需要支持 fully normalizing字符在文档中根据 XML 1.1 ] [附录E，这个参数必须是默认激活如果支持。

"xml-declaration"

true

[要求]（默认）如果一个 Document， Element，或 Entity节点序列化的XML声明，或文本声明，应包括。版本（ Document.xmlVersion如果文件是3级文件的版本和非空，否则使用值“1”），和输出编码（见 LSSerializer.write有关如何找到输出编码）是序列化的XML声明中指定。

false

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

getNewLine

String getNewLine()

在XML中使用的字符的行序列的结尾被写出来。任何字符串型，但XML将只有一组特定的字符序列作为行结束（见2.11节，“行尾处理”[ XML 1.0 ]，如果序列化的XML内容是1或2.11节，“行尾处理”[ XML 1.1 ]，如果序列化的内容是XML 1.1）。使用比推荐的结果在一个不可串行化或形成不好的文档中的其他字符序列）。
检索，该属性的默认值是线序实现特定的默认端。DOM实现应该选择默认的比赛环境中使用的文本文件的惯例。实现必须选择一个默认的序列匹配一个由XML XML允许1或1.1，取决于序列化的内容。设置此属性的值 null将重置为默认值。

setNewLine

void setNewLine(String newLine)

在XML中使用的字符的行序列的结尾被写出来。任何字符串型，但XML将只有一组特定的字符序列作为行结束（见2.11节，“行尾处理”[ XML 1.0 ]，如果序列化的XML内容是1或2.11节，“行尾处理”[ XML 1.1 ]，如果序列化的内容是XML 1.1）。使用比推荐的结果在一个不可串行化或形成不好的文档中的其他字符序列）。
检索，该属性的默认值是线序实现特定的默认端。DOM实现应该选择默认的比赛环境中使用的文本文件的惯例。实现必须选择一个默认的序列匹配一个由XML XML允许1或1.1，取决于序列化的内容。设置此属性的值 null将重置为默认值。

getFilter

LSSerializerFilter getFilter()

当应用程序提供了一个过滤器，序列化程序将调用出来的滤波器在序列化的每个节点。过滤器的实现可以选择从流中删除节点或终止序列化早期。
过滤器是通过的 DOMConfiguration参数要求操作后已应用。例如，CDATA部分不会如“ cdata-sections”设置为 false通过过滤器。

setFilter

void setFilter(LSSerializerFilter filter)

当应用程序提供了一个过滤器，序列化程序将调用出来的滤波器在序列化的每个节点。过滤器的实现可以选择从流中删除节点或终止序列化早期。
过滤器是通过的 DOMConfiguration参数要求操作后已应用。例如，CDATA部分不会如“ cdata-sections”设置为 false通过过滤器。

write

boolean write(Node nodeArg,
              LSOutput destination)
       throws LSException

将指定的节点如上面所描述的对 LSSerializer接口的一般描述。输出写入提供 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“如果他们希望得到的错误信息。

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
            throws LSException

一个方便的方法，好像 LSSerializer.write被称为一个没有编码指定 LSOutput.systemId设置为 uri争论 LSOutput。

参数

nodeArg -序列化节点。

uri - URI写。

结果

如果成功返回 true node序列化。返回 false如果正常处理停止但执行保存序列化文件；序列化的结果是依赖于实现的。

异常

LSException - serialize_err：如果 LSSerializer无法序列化节点提出。DOM应用程序应该附上一 DOMErrorHandler使用参数“ error-handler“如果他们希望得到的错误信息。

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应用程序应该附上一 DOMErrorHandler使用参数“ error-handler“如果他们希望得到的错误信息。