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

接口 LSParser

public interface LSParser
能够从各种输入源构建或扩充 DOM 树的对象的接口。

LSParser提供了解析XML和构建相应DOM文档结构的API。 LSParser 实例可以通过调用 DOMImplementationLS.createLSParser() 方法获得。

如 [DOM 3 级核心 ] 中所指定，当文档首次通过 LSParser 可用时：

  • 永远不会有两个相邻的 NODE_TEXT 类型的节点，也永远不会有空文本节点。
  • 预计 Attr 节点的 value 和 nodeValue 属性最初返回 XML 1.0 规范化值 。但是，如果参数“验证模式”和“数据类型规范化”设置为true，根据使用的属性规范化，属性值可能与通过 XML 1.0 属性规范化获得的属性值不同。如果参数“数据类型规范化”设置为false，则保证发生 XML 1.0 属性规范化，如果属性列表不包含名称空间声明，Element 节点上的 attributes 属性表示属性[属性]在 [XML 信息集] 中定义。

异步 LSParser 对象也应实现 events::EventTarget 接口，以便可以在异步 LSParser 对象上注册事件监听器。

异步 LSParser 对象支持的事件有：

load
LSParser 完成加载文档。另请参阅 LSLoadEvent 接口的定义。
progress
LSParser 在解析数据时发出进度信号。本规范不尝试准确定义进度事件应在何时发送。这是有意保留为依赖于实现的。下面是一个应用程序可能如何调度进度事件的示例：一旦解析器开始接收数据，就会调度一个进度事件以指示解析开始。从那里开始，每接收和处理 4096 字节的数据就会调度一个进度事件。不过，这只是一个示例，实现可以选择在解析时随时分派进度事件，或者根本不分派它们。另请参阅 LSProgressEvent 接口的定义。

笔记：本规范中定义的所有事件都使用命名空间 URI "http://www.w3.org/2002/DOMLS"。

在解析输入源时，错误会通过错误处理程序（LSParser.domConfig 的“错误处理器”参数）报告给应用程序。本规范绝不试图定义在解析 XML 或任何其他标记时可能发生的所有可能错误，但定义了一些常见的错误情况。本规范定义的错误和警告类型（DOMError.type）是：

"check-character-normalization-failure" [error]
如果参数“检查字符规范化”设置为 true 并且遇到未通过规范化检查的字符串，则引发。
"doctype-not-allowed" [fatal]
如果配置参数“disallow-doctype”设置为 true 并且遇到文档类型，则引发。
"no-input-specified" [fatal]
加载文档且未在 LSInput 对象中指定输入时引发。
"pi-base-uri-not-preserved" [warning]
如果在无法保留处理指令的基本 URI 的位置遇到处理指令，则引发。如果配置参数“实体”设置为 false 并且解析以下 XML 文件： 
 <!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]>
 <root> &e; </root>
和 subdir/myentity.ent 包含： 
<one> <two/> </one> <?pi 3.14159?>
 <more/>
，则会引发此警告的情况的一个示例
"unbound-prefix-in-entity" [warning]
如果配置参数“namespaces”设置为 true 并且在实体的替换文本中遇到未绑定的命名空间前缀，则可能会引发依赖于实现的警告。不会强制发出此警告，因为某些现有解析器可能无法识别实体替换文本中的未绑定命名空间前缀。
"unknown-character-denormalization" [fatal]
如果配置参数“ignore-unknown-character-denormalizations”设置为 false 并且遇到处理器无法确定其规范化属性的字符，则引发。
"unsupported-encoding" [fatal]
如果遇到不支持的编码，则引发。
"unsupported-media-type" [fatal]
如果配置参数“supported-media-types-only”设置为 true 并且遇到不支持的媒体类型，则引发。

除了引发已定义的错误和警告之外，实现还应针对任何其他错误和警告情况引发特定于实现的错误和警告，例如 IO 错误（未找到文件、权限被拒绝...）、XML 格式正确性错误、等等。

另见 文档对象模型 (DOM) 级别 3 加载和保存规范 。

自从：
1.5

  • 字段摘要

    字段
    修饰符和类型
    Field
    描述
    static final short
    ACTION_APPEND_AS_CHILDREN
    将解析操作的结果附加为上下文节点的子节点。
    static final short
    ACTION_INSERT_AFTER
    将解析操作的结果插入上下文节点的紧随其后的同级节点。
    static final short
    ACTION_INSERT_BEFORE
    将解析操作的结果作为上下文节点的前一个同级插入。
    static final short
    ACTION_REPLACE
    用解析操作的结果替换上下文节点。
    static final short
    ACTION_REPLACE_CHILDREN
    用解析操作的结果替换上下文节点的所有子节点。

  • 方法总结

    修饰符和类型
    方法
    描述
    void
    abort()
    中止加载当前由 LSParser 加载的文档。
    boolean
    getAsync()
    true 如果 LSParser 是异步的，false 如果是同步的。
    boolean
    getBusy()
    true 如果 LSParser 当前正忙于加载文档，否则 false 。
    DOMConfiguration
    getDomConfig()
    解析输入源时使用的 DOMConfiguration 对象。
    LSParserFilter
    getFilter()
    当提供过滤器时，实现将调用过滤器，因为它正在构建 DOM 树结构。
    Document
    parse(LSInput input)
    从 LSInput 标识的资源中解析 XML 文档。
    Document
    parseURI(String uri)
    从 URI 引用 [IETF RFC 2396] 标识的位置解析 XML 文档。
    Node
    parseWithContext(LSInput input, Node contextArg, short action)
    从 LSInput 标识的资源中解析 XML 片段，并将内容插入现有文档中由 context 和 action 参数指定的位置。
    void
    setFilter(LSParserFilter filter)
    当提供过滤器时，实现将调用过滤器，因为它正在构建 DOM 树结构。

  • 字段详细信息

    • ACTION_APPEND_AS_CHILDREN

      static final short ACTION_APPEND_AS_CHILDREN
      将解析操作的结果附加为上下文节点的子节点。要使此操作起作用，上下文节点必须是 Element 或 DocumentFragment。
      参见：

    • ACTION_REPLACE_CHILDREN

      static final short ACTION_REPLACE_CHILDREN
      用解析操作的结果替换上下文节点的所有子节点。要使此操作生效，上下文节点必须是 Element、Document 或 DocumentFragment。
      参见：

    • ACTION_INSERT_BEFORE

      static final short ACTION_INSERT_BEFORE
      将解析操作的结果作为上下文节点的前一个同级插入。要使此操作起作用，上下文节点的父节点必须是 Element 或 DocumentFragment。
      参见：

    • ACTION_INSERT_AFTER

      static final short ACTION_INSERT_AFTER
      将解析操作的结果插入上下文节点的紧随其后的同级节点。要使此操作起作用，上下文节点的父节点必须是 Element 或 DocumentFragment。
      参见：

    • ACTION_REPLACE

      static final short ACTION_REPLACE
      用解析操作的结果替换上下文节点。要使此操作起作用，上下文节点必须有父节点，并且父节点必须是 Element 或 DocumentFragment 。
      参见：

  • 方法详情

    • getDomConfig

      DOMConfiguration  getDomConfig()
      解析输入源时使用的 DOMConfiguration 对象。这个 DOMConfiguration 特定于解析操作。此 DOMConfiguration 对象的任何参数值都不会自动传递给解析操作创建或使用的 Document 上的 DOMConfiguration 对象。 DOM 应用程序负责将任何需要的参数值从此 DOMConfiguration 对象传递到 Document 对象引用的 DOMConfiguration 对象。
      除了在 [DOM 3 级核心 ] 中定义的 DOMConfiguration 接口上识别的参数外，LSParser 的 DOMConfiguration 对象添加或修改以下参数：
      "charset-overrides-xml-encoding"
      true
      [optional ] (default ) 如果更高级别的协议（例如 HTTP [IETF RFC 2616 ]）提供了正在处理的输入流的字符编码的指示，这将覆盖 XML 声明或文本声明中指定的任何编码（另请参见第 4.3 节） .3，“实体中的字符编码”，在 [XML 1.0 ]) 中。在 LSInput 中明确设置编码会覆盖协议中的任何编码。
      false
      [required ] 解析器忽略来自更高级别协议的任何字符集编码信息。
      "disallow-doctype"
      true
      [optional] 抛出致命一击“文档类型不允许”如果在解析文档时发现文档类型节点，则会出错。这在处理诸如不允许文档类型节点的 SOAP 信封之类的事情时很有用。
      false
      [required ] (default ) 允许文档中的文档类型节点。
      "ignore-unknown-character-denormalizations"
      true
      [required ] (default ) 如果在支持 [XML 1.1 ] 时验证完全规范化，处理器遇到无法确定规范化属性的字符，则处理器将忽略由这些字符引起的任何可能的非规范化。 [XML 1.0] 忽略此参数。
      false
      [optional ] 报告一个致命的“未知字符非规范化”如果遇到处理器无法确定规范化属性的字符，则会出错。
      "infoset"
      有关此参数的说明，请参阅 DOMConfiguration 的定义。与 [DOM 3 级核心] 不同，此参数对于 LSParser 将默认为 true。
      "namespaces"
      true
      [required ] (default ) 执行 [XML 命名空间 ] 和 [XML 命名空间 1.1 ] 中定义的命名空间处理。
      false
      [optional ] 不执行名称空间处理。
      "resource-resolver"
      [required ] 对 LSResourceResolver 对象的引用，或 null。如果在遇到外部资源（例如外部 XML 实体或 XML 模式位置）时此参数的值不为 null，则实现将请求此参数中引用的 LSResourceResolver 解析该资源。
      "supported-media-types-only"
      true
      [optional ] 检查已解析资源的媒体类型是否为受支持的媒体类型。如果遇到不受支持的媒体类型，则会出现类型的致命错误“不支持的媒体类型”将被提高。 [IETF RFC 3023] 中定义的媒体类型必须始终被接受。
      false
      [required ] (default ) 接受任何媒体类型。
      "validate"
      有关此参数的说明，请参阅 DOMConfiguration 的定义。与 [DOM 3 级核心 ] 不同，内部子集的处理始终完成，即使此参数设置为 false 也是如此。
      "validate-if-schema"
      有关此参数的说明，请参阅 DOMConfiguration 的定义。与 [DOM 3 级核心 ] 不同，内部子集的处理始终完成，即使此参数设置为 false 也是如此。
      "well-formed"
      有关此参数的说明，请参阅 DOMConfiguration 的定义。与 [DOM 3 级核心] 不同，此参数不能设置为 false。

    • getFilter

      LSParserFilter  getFilter()
      当提供过滤器时，实现将调用过滤器，因为它正在构建 DOM 树结构。过滤器可以选择从正在构建的文档中删除元素，或者提前终止解析。
      在应用了 DOMConfiguration 参数请求的操作后调用过滤器。例如，如果“validate”设置为 true，则在调用过滤器之前完成验证。

    • setFilter

      void setFilter(LSParserFilter  filter)
      当提供过滤器时，实现将调用过滤器，因为它正在构建 DOM 树结构。过滤器可以选择从正在构建的文档中删除元素，或者提前终止解析。
      在应用了 DOMConfiguration 参数请求的操作后调用过滤器。例如，如果“validate”设置为 true，则在调用过滤器之前完成验证。

    • getAsync

      boolean getAsync()
      true 如果 LSParser 是异步的，false 如果是同步的。

    • getBusy

      boolean getBusy()
      true 如果 LSParser 当前正忙于加载文档，否则 false 。

    • parse

      Document  parse(LSInput  input) throws DOMException , LSException
      从 LSInput 标识的资源中解析 XML 文档。
      参数：
      input - 要从中读取文档源的 LSInput。
      返回：
      如果 LSParser 是同步的 LSParser ，则返回新创建和填充的 Document。如果 LSParser 是异步的，则返回 null，因为此方法返回时文档对象可能尚未构建。
      抛出：
      DOMException - INVALID_STATE_ERR：如果 LSParser 的 LSParser.busy 属性为 true 则引发。
      LSException - PARSE_ERR：在 LSParser 无法加载 XML 文档时引发。如果 DOM 应用程序希望获得有关错误的详细信息，则应使用参数“错误处理器”附加一个 DOMErrorHandler。

    • parseURI

      Document  parseURI(String  uri) throws DOMException , LSException
      从 URI 引用 [IETF RFC 2396] 标识的位置解析 XML 文档。如果 URI 包含片段标识符（请参阅 [IETF RFC 2396] 中的第 4.1 节），则该行为未由本规范定义，本规范的未来版本可能会定义该行为。
      参数：
      uri - 要读取的 XML 文档的位置。
      返回：
      如果 LSParser 是同步的 LSParser ，则返回新创建和填充的 Document，如果发生错误则返回 null。如果 LSParser 是异步的，则返回 null，因为此方法返回时文档对象可能尚未构建。
      抛出：
      DOMException - INVALID_STATE_ERR：如果 LSParser.busy 属性为 true 则引发。
      LSException - PARSE_ERR：在 LSParser 无法加载 XML 文档时引发。如果 DOM 应用程序希望获得有关错误的详细信息，则应使用参数“错误处理器”附加一个 DOMErrorHandler。

    • parseWithContext

      Node  parseWithContext(LSInput  input, Node  contextArg, short action) throws DOMException , LSException
      从 LSInput 标识的资源中解析 XML 片段，并将内容插入现有文档中由 context 和 action 参数指定的位置。解析输入流时，上下文节点（或其父节点，取决于将插入结果的位置）用于解析未绑定的命名空间前缀。上下文节点的 ownerDocument 节点（如果节点类型为 DOCUMENT_NODE 则为节点本身）用于解析默认属性和实体引用。
      当新数据插入到文档中时，上下文节点的每个新的直接子节点或同级节点至少会触发一个突变事件。
      如果上下文节点是 Document 节点并且操作是 ACTION_REPLACE_CHILDREN ，那么作为上下文节点传递的文档将被更改，这样它的 xmlEncoding 、 documentURI 、 xmlVersion 、 inputEncoding 、 xmlStandalone 和所有其他此类属性都设置为它们如果使用 LSParser.parse() 解析输入源，则将设置为。
      此方法始终是同步的，即使 LSParser 是异步的（LSParser.async 是 true ）。
      如果解析时发生错误，调用者将通过与 DOMConfiguration 的“错误处理器 ”参数关联的 ErrorHandler 实例得到通知。
      调用 parseWithContext 时，将忽略以下配置参数的值，并始终使用它们的默认值：“validate”、“验证模式”和“元素内容空白”。其他参数将被正常处理，解析器将调用 LSParserFilter 就像解析整个文档一样。
      参数：
      input - 要从中读取源文档的 LSInput。源文档必须是 XML 片段，即除了完整的 XML 文档之外的任何内容（上下文节点类型为 DOCUMENT_NODE 且操作为 ACTION_REPLACE_CHILDREN 的情况除外）、DOCTYPE（内部子集）、实体声明、符号声明，或 XML 或文本声明。
      contextArg - 用作正在解析的数据的上下文的节点。此节点必须是Document 节点、DocumentFragment 节点或允许作为Element 节点子节点的类型的节点，例如它不能是Attribute 节点。
      action - 该参数描述了在插入的新节点集和上下文节点的现有子节点之间应采取的操作。上面的 ACTION_TYPES 中定义了一组可能的操作。
      返回：
      返回作为解析操作结果的节点。如果结果是多个顶级节点，则返回第一个。
      抛出：
      DOMException - HIERARCHY_REQUEST_ERR：如果内容无法替换、插入到上下文节点之前、之后或作为上下文节点的子节点，则引发（另请参见 [DOM 3 级核心 ] 中的 Node.insertBefore 或 Node.replaceChild）。
      NOT_SUPPORTED_ERR：如果 LSParser 不支持此方法，或者如果上下文节点是 Document 类型并且 DOM 实现不支持替换 DocumentType 子节点或 Element 子节点，则引发。
      NO_MODIFICATION_ALLOWED_ERR：如果上下文节点是只读节点并且内容被附加到其子列表，或者如果上下文节点的父节点是只读节点并且内容被插入到其子列表中，则引发。
      INVALID_STATE_ERR：如果 LSParser.busy 属性为 true 则引发。
      LSException - PARSE_ERR：如果 LSParser 无法加载 XML 片段则引发。如果 DOM 应用程序希望获得有关错误的详细信息，则应使用参数“错误处理器”附加一个 DOMErrorHandler。

    • abort

      void abort()
      中止加载当前由 LSParser 加载的文档。如果 LSParser 当前不忙，则调用此方法不会执行任何操作。