```
public interface LSParser
```
能够从各种输入源构建或增加DOM树的对象的接口。
LSParser提供了一个用于解析XML和构建相应的DOM文档结构的API。可以通过调用DOMImplementationLS.createLSParser()方法获得LSParser实例。

如[ DOM Level 3 Core ]中所述，当首次通过LSParser提供文档时：
- 将不会有两个类型为NODE_TEXT的相邻节点，并且永远不会有空文本节点。
- 预计Attr节点的value和nodeValue属性最初将返回XML 1.0 normalized value 。但是，如果参数“ validate-if-schema ”和“ datatype-normalization ”设置为true ，则根据所使用的属性标准化，属性值可能与通过XML 1.0属性归一化获得的属性值不同。如果参数“ datatype-normalization ”设置为false ，则XML 1.0属性规范化将被保证发生，如果属性列表不包含命名空间声明，则Element节点上的attributes属性表示[ XML Information Set ]中定义的属性[attributes ]。
异步LSParser对象预期也将实现events::EventTarget接口，以便可以在异步LSParser对象上注册事件侦听器。

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

加载

LSParser完成加载文档。另请参阅LSLoadEvent界面的定义。

进展

LSParser在数据解析时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并遇到一个doctype，则true 。

"no-input-specified" [fatal]

在LSInput对象中指定加载文档时未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并且遇到处理器无法确定归一化属性的字符，则false 。

"unsupported-encoding" [fatal]

如果遇到不受支持的编码，则引发。

"unsupported-media-type" [fatal]

如果配置参数“supported-media-types-only-only”设置为true并且遇到不支持的介质类型，则true 。
除了提出定义的错误和警告之外，预计实施将会针对任何其他错误和警告情况（如IO错误（未找到文件，拒绝许可，...），XML格式良好错误，等等。

另见Document Object Model (DOM) Level 3 Load and Save Specification 。
从以下版本开始：

1.5

Field Summary

Fields
Modifier and Type	Field	描述
`static short`	`ACTION_APPEND_AS_CHILDREN`	将解析操作的结果附加到上下文节点的子节点。
`static short`	`ACTION_INSERT_AFTER`	将解析操作的结果作为上下文节点的紧跟同步插入。
`static short`	`ACTION_INSERT_BEFORE`	将解析操作的结果作为前一个上下文节点的同级插入。
`static short`	`ACTION_REPLACE`	用解析操作的结果替换上下文节点。
`static short`	`ACTION_REPLACE_CHILDREN`	用解析操作的结果替换上下文节点的所有子节点。

方法摘要

所有方法接口方法抽象方法
Modifier and Type	方法	描述
`void`	`abort()`	中止加载 `LSParser`当前正在加载的 `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 。
    
    另请参见：
    
    Constant Field Values
  - ACTION_REPLACE_CHILDREN
```
static final short ACTION_REPLACE_CHILDREN
```
    用解析操作的结果替换上下文节点的所有子节点。为了使此动作有效，上下文节点必须是Element ，一个Document或者DocumentFragment 。
    
    另请参见：
    
    Constant Field Values
  - ACTION_INSERT_BEFORE
```
static final short ACTION_INSERT_BEFORE
```
    将解析操作的结果作为前一个上下文节点的同级插入。要使此操作工作，上下文节点的父级必须是Element或DocumentFragment 。
    
    另请参见：
    
    Constant Field Values
  - ACTION_INSERT_AFTER
```
static final short ACTION_INSERT_AFTER
```
    将解析操作的结果作为上下文节点的紧跟同步插入。要使此操作工作，上下文节点的父级必须是Element或DocumentFragment 。
    
    另请参见：
    
    Constant Field Values
  - ACTION_REPLACE
```
static final short ACTION_REPLACE
```
    用解析操作的结果替换上下文节点。要使此操作正常工作，上下文节点必须具有父级，父级必须为Element或DocumentFragment 。
    
    另请参见：
    
    Constant Field Values
- 方法详细信息
  - getDomConfig
```
DOMConfiguration getDomConfig()
```
    解析输入源时使用的DOMConfiguration对象。这个DOMConfiguration是特定于解析操作的。此DOMConfiguration对象中的参数值不会自动传递到由解析操作创建或使用的DOMConfiguration上的Document对象。 DOM应用程序负责将所需的参数值从该DOMConfiguration对象传递到由DOMConfiguration对象引用的Document对象。
    除了上识别的参数DOMConfiguration中定义的接口[ DOM Level 3 Core ]时， DOMConfiguration对象为LSParser添加或修改下列参数：
    
    "charset-overrides-xml-encoding"
    
    true
    
    [ 可选 ]（ 默认值 ）如果诸如HTTP [ IETF RFC 2616 ]之类的较高级协议提供正在处理的输入流的字符编码的指示，则将覆盖XML声明或文本声明中指定的任何编码（另见第4.3节.3，“实体中的字符编码”，在[ XML 1.0 ]）。明确地设置LSInput的编码将覆盖协议中的任何编码。
    
    false
    
    [ 必需 ]解析器忽略来自上级协议的任何字符集编码信息。
    
    "disallow-doctype"
    
    true
    
    [ 可选 ]如果在解析文档时找到了一个doctype节点，则会抛出一个致命的“doctype-not-allowed”错误。这在处理不允许doctype节点的SOAP信封的事情时很有用。
    
    false
    
    [ 必需 ]（默认）允许文档中的doctype节点。
    
    "ignore-unknown-character-denormalizations"
    
    true
    
    [ 必需 ]（默认）如果在支持[ XML 1.1 ]时验证完全归一化，则处理器遇到无法确定归一化属性的字符，则处理器将忽略由这些字符引起的任何可能的非规格化。 [ XML 1.0 ]忽略此参数。
    
    false
    
    [ 可选 ]如果遇到处理器无法确定归一化属性的字符，则报告致命的“未知字符反规范化”错误。
    
    "infoset"
    
    有关此参数的描述，请参阅DOMConfiguration的定义。与在[ DOM Level 3 Core ]，该参数将默认为true为LSParser 。
    
    "namespaces"
    
    true
    
    [ 必需 ]（默认）执行[ XML Namespaces ]和[ XML Namespaces 1.1 ]中定义的命名空间处理。
    
    false
    
    [ 可选 ]不要执行命名空间处理。
    
    "resource-resolver"
    
    [ 必需 ]对LSResourceResolver对象的引用，或null。如果遇到外部资源（如外部XML实体或XML模式位置）时，此参数的值不为空，则该实现将请求此参数中引用的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()
```
    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则 true 。
    
    LSException - PARSE_ERR：如果LSParser无法加载XML文档，则引发。如果DOM应用程序希望获取有关错误的详细信息， DOMErrorHandler使用参数“ 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则 true 。
    
    LSException - PARSE_ERR：如果LSParser无法加载XML文档，则引发。如果DOM应用程序希望获得有关错误的详细信息， DOMErrorHandler使用参数“ 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 ）。
    如果在分析中发生错误，呼叫者通过通知ErrorHandler与“相关实例error-handler所述的”参数DOMConfiguration 。
    当调用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：如果内容无法替代，在上下文节点之前，之后或子节点插入（另见[ DOM Level 3 Core ]中的Node.insertBefore或Node.replaceChild ））。
    NOT_SUPPORTED_ERR：如果LSParser不支持此方法，或者如果上下文节点的类型为Document ，并且DOM实现不支持替换DocumentType子Element或Element子节点，则Element 。
    NO_MODIFICATION_ALLOWED_ERR：如果上下文节点是只读节点并且内容正在追加到其子列表，或者上下文节点的父节点是只读节点，并且内容正在其子节点列表中，则引发。
    INVALID_STATE_ERR：如果LSParser.busy属性为true则true 。
    
    LSException - PARSE_ERR：如果LSParser无法加载XML片段，则引发。如果DOM应用程序希望获取有关错误的详细信息， DOMErrorHandler使用参数“ error-handler ”附加DOMErrorHandler 。
  - abort
```
void abort()
```
    Abort the loading of the document that is currently being loaded by the LSParser. If the LSParser is currently not busy, a call to this method does nothing.

Interface LSParser

Field Summary

方法摘要

字段详细信息

ACTION_APPEND_AS_CHILDREN

ACTION_REPLACE_CHILDREN

ACTION_INSERT_BEFORE

ACTION_INSERT_AFTER

ACTION_REPLACE

方法详细信息

getDomConfig

getFilter

setFilter

getAsync

getBusy

parse

parseURI

parseWithContext

abort