模块  java.xml
软件包  org.w3c.dom.ls

Interface LSSerializer

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

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

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

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

    在标记内，但在属性之外，任何无法在输出字符编码中表示的字符的出现都会报告为致命错误DOMError 。 一个例子是序列化元素<LaCañADA />与encoding="us-ascii" 。 这将导致产生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时，无论字节顺序标记是否被序列化，或者输出是big-endian还是little-endian，都取决于实现。 当编码为UTF-16时，输出是否为big-endian或little-endian是依赖于实现的，但必须为非字符输出生成字节顺序标记，例如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

    • 方法摘要

      所有方法  实例方法 抽象方法 
      变量和类型 方法 描述
      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 。 虽然DOM实现不需要根据[ XML 1.1 ]的附录E支持fully normalizing文档中的字符，但如果支持，则必须默认激活此参数。
        "xml-declaration"
        true
        [ 需要 ]（ 默认 ）如果Document ， Element ，或Entity节点被序列化，XML声明，或文本声明，应该包括在内。 版本（ Document.xmlVersion如果文档是Level 3文档且版本为非null，否则使用值“1.0”），输出编码（有关如何查找输出编码的详细信息，请参阅LSSerializer.write ）在序列化的XML声明。
        false
        [ 必需 ]不要序列化XML和文本声明。 报告"xml-declaration-needed"警告是否会导致问题（即序列化数据是[ XML 1.0 ]以外的XML版本，或者需要编码才能重新解析序列化数据）。

      • getNewLine

        String getNewLine()
        要写出的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会将其值重置为默认值。

      • 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 ， false会将CDATA节传递给过滤器。

      • write

        boolean write​(Node nodeArg,              LSOutput destination)       throws LSException
        如上所述在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无法序列化节点，则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。
        结果
        返回true如果node成功序列化。 如果正常处理停止但返回false ，则执行保持序列化文档; 然后，序列化的结果依赖于实现。
        异常
        LSException - SERIALIZE_ERR：如果LSSerializer无法序列化节点，则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 。
        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.