|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
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 编写时将输出实体扩展，但不执行名称空间修复。得到的输出将作为有效的外部实体。
true，则把 EntityReference 节点序列化为输出中形式 " &entityName;" 的实体引用。将忽略实体引用的子节点（扩展）。如果参数 "entities" 设置为 false，则仅序列化实体引用的子项。将始终序列化不带有子项的 EntityReference 节点（没有相应的 Entity 节点，或者相应的 Entity 节点没有子节点）。
CDATAsections 包括不能用指定的输出编码表示的内容字符，将根据 "split-cdata-sections" 参数对其进行处理。如果将该参数设置为 true，则将拆分 CDATAsections，将不可表示的字符序列化为普通内容中的数字字符引用。不指定拆分的精确位置和数量。如果参数设置为 false，则参数 "well-formed" 设置为 true 时，CDATAsection 中不可表示的字符将报告为 "wf-invalid-character" 错误。该错误不可恢复 - 没有提供替换字符和继续进行序列化的机制。
DocumentFragment 节点可通过按照文档片段的子片断在文档片断中出现的顺序序列化这些子片断得以序列化。
注：序列化 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] 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 参数。 |
| 方法详细信息 |
|---|
DOMConfiguration getDomConfig()
LSSerializer 使用的 DOMConfiguration 对象。LSSerializer 的 DOMConfiguration 对象还将添加或修改以下参数：
"canonical-form"truetrue 将把参数 "format-pretty-print"、"discard-default-content" 和 "xml-declaration " 设置为 false。将其中的一个参数设置为 true 将把此参数设置为 false。当 "canonical-form" 为 true 时序列化 XML 1.1 文档将生成严重错误。 false。"discard-default-content"trueAttr.specified 属性来决定必须丢弃哪些属性。注意，有些实现可能使用任何可供实现使用的信息（即 XML 模式、DTD、Attr.specified 属性等）来决定在此参数设置为 true 时应丢弃哪些属性和内容。 false。"format-pretty-print"truefalse。"ignore-unknown-character-denormalizations" true"unknown-character-denormalization" 警告（而不是像未设置此参数那样引发错误），并将忽略由这些字符引起的任何可能的反向标准化。 false。"normalize-characters"DOMConfiguration 定义的参数等效。与在 Core 中不同，此参数的默认值是 true。尽管根据 [XML 1.1] 中的附录 E 的规定，不需要 DOM 实现支持完全标准化文档中的字符，但如果支持，则默认情况下必须激活此参数。 "xml-declaration"trueDocument、Element 或 Entity 节点被序列化，则必须包括 XML 声明或文本声明。版本（如果文档是 Level 3 文档并且版本为非 null，则使用 Document.xmlVersion，否则使用值 "1.0"）和输出编码（关于如何查找输出编码的详细信息请参见 LSSerializer.write ）在已序列化的 XML 声明中指定。false。"xml-declaration-needed" 警告。
String getNewLine()
null 将把其值重置为默认值。
void setNewLine(String newLine)
null 将把其值重置为默认值。
LSSerializerFilter getFilter()
DOMConfiguration 参数请求的操作后调用。例如，如果把 "cdata-sections" 设置为 false，则不会将 CDATA 节传递给过滤器。
void setFilter(LSSerializerFilter filter)
DOMConfiguration 参数请求的操作后调用。例如，如果把 "cdata-sections" 设置为 false，则不会将 CDATA 节传递给过滤器。
boolean write(Node nodeArg,
LSOutput destination)
throws LSException
LSSerializer 接口的一般介绍中所描述的那样序列化指定的节点。将输出写入所提供的 LSOutput。LSOutput 写入时，编码可以通过查找可通过 LSOutput 获得的编码信息和按如下顺序编写的条目（或者其所有者文档）来发现：
LSOutput.encoding,
Document.inputEncoding,
Document.xmlEncoding.
LSOutput 中未指定输出，则将引发 "no-output-specified" 严重错误。
nodeArg - 将序列化的节点。destination - 已序列化 DOM 的目标。
node 被成功序列化，则返回 true。如果常规处理停止，但实现仍在序列化文档，则返回 false；序列化的结果是具有实现依赖性。
LSException - SERIALIZE_ERR:如果 LSSerializer 不能序列化节点，则引发此异常。如果 DOM 应用程序想获得有关错误的详细信息，则它必须附加上使用参数 "error-handler" 的 DOMErrorHandler。
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。
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。
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。