Module java.xml
Package org.w3c.dom.ls

Interface LSParser

public interface LSParser
一个能够从各种输入源构建或增强DOM树的对象的接口。

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

根据[DOM Level 3 Core]的规定，当文档首次通过LSParser可用时：

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

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

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

load
LSParser完成加载文档。另请参阅LSLoadEvent接口的定义。
progress
LSParser在解析数据时发出进度信号。本规范不试图精确定义何时应分派进度事件。这是故意留给实现相关的。以下是一个应用程序可能如何分派进度事件的示例：一旦解析器开始接收数据，将分派进度事件以指示解析开始。从那时起，对于接收和处理的每4096字节数据，将分派一个进度事件。这只是一个示例，实现可以选择在解析过程中的任何时间分派进度事件，或根本不分派。另请参阅LSProgressEvent接口的定义。

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

在解析输入源时，错误通过错误处理程序(LSParser.domConfig的"error-handler"参数)报告给应用程序。本规范无论如何都不会尝试定义解析XML或任何其他标记时可能发生的所有可能错误，但定义了一些常见的错误情况。本规范定义的错误和警告类型(DOMError.type)包括：

"check-character-normalization-failure" [error]
如果参数"check-character-normalization"设置为true并遇到无法通过规范化检查的字符串，则引发。
"doctype-not-allowed" [fatal]
如果配置参数"disallow-doctype"设置为true并遇到文档类型，则引发。
"no-input-specified" [fatal]
在加载文档时未指定LSInput对象中的输入时引发。
"pi-base-uri-not-preserved" [warning]
如果在无法保留处理指令的基本URI的位置遇到处理指令，则引发警告。一个引发此警告的示例是，如果配置参数"entities"设置为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) Level 3 Load and Save Specification。

自从:
1.5

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    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
    用解析操作的结果替换上下文节点的所有子节点。

  • Method Summary

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

  • Field Details

    • 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。
      另请参阅:

  • Method Details

    • getDomConfig

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

    • getFilter

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

    • setFilter

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

    • getAsync

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

    • getBusy

      boolean getBusy()
      如果LSParser当前正在忙于加载文档，则为true，否则为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应用程序希望获取有关错误的详细信息，则应使用参数"error-handler"附加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应用程序希望获取有关错误的详细信息，则应使用参数"error-handler"附加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的"error-handler"参数关联的ErrorHandler实例收到通知。
      在调用parseWithContext时，以下配置参数的值将被忽略，其默认值将始终被使用："validate"、"validate-if-schema"和"element-content-whitespace"。其他参数将被正常处理，解析器应该像解析整个文档一样调用LSParserFilter。
      参数:
      input - 要读取源文档的LSInput。源文档必须是XML片段，即除了完整的XML文档（除非上下文节点为DOCUMENT_NODE类型且操作为ACTION_REPLACE_CHILDREN）外的任何内容，DOCTYPE（内部子集）、实体声明、符号声明或XML或文本声明。
      contextArg - 用作正在解析数据的上下文的节点。此节点必须是Document节点、DocumentFragment节点或允许作为Element节点的子节点的类型的节点，例如不能是Attribute节点。
      action - 此参数描述应在新插入的节点集和上下文节点的现有子节点之间采取的操作。可能的操作集在上面的ACTION_TYPES中定义。
      返回:
      返回解析操作的结果节点。如果结果有多个顶级节点，则返回第一个节点。
      抛出:
      DOMException - HIERARCHY_REQUEST_ERR: 如果内容无法替换、插入到上下文节点之前、之后或作为其子节点（另请参阅Node.insertBefore或Node.replaceChild在[DOM Level 3 Core]中)时引发。
      NOT_SUPPORTED_ERR: 如果LSParser不支持此方法，或者上下文节点为Document类型且DOM实现不支持替换DocumentType子节点或Element子节点时引发。
      NO_MODIFICATION_ALLOWED_ERR: 如果上下文节点是只读节点且内容正在追加到其子节点列表中，或者如果上下文节点的父节点是只读节点且内容正在插入到其子节点列表中时引发。
      INVALID_STATE_ERR: 如果LSParser.busy属性为true时引发。
      LSException - PARSE_ERR: 如果LSParser无法加载XML片段。如果DOM应用程序希望获取有关错误的详细信息，应使用参数"error-handler"附加一个DOMErrorHandler。

    • abort

      void abort()
      中止LSParser当前正在加载的文档。如果LSParser当前未忙碌，则调用此方法不会产生任何效果。