compact2, compact3

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 normalized value 。 然而，如果将参数“ validate-if-schema ”和“ datatype-normalization ”设置为true ，则根据所使用的属性标准化，属性值可能与通过XML 1.0属性归一化获得的属性值不同。 如果参数“ datatype-normalization ”设置为false ，所述XML 1.0属性标准化保证发生，并且如果所述属性列表中不包含的命名空间声明，则attributes上属性Element节点代表属性[属性]在[定义XML Information Set ]。

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

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

加载

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

进展

当数据被解析时， LSParser表示进展。 这个规范并不会试图准确地定义进度事件应该被调度的时间。 这是有意留作为实现依赖的。 以下是应用程序如何调度进度事件的一个示例：解析器开始接收数据后，将调度progress事件以指示解析开始。 从那里开始，为接收和处理的每4096字节的数据调度进度事件。 这只是一个例子，而实现可以选择在解析时随时调度进度事件，或者根本不派发进度事件。 另请参阅LSProgressEvent界面的定义。

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

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

"check-character-normalization-failure" [error]

如果参数“ check-character-normalization ”设置为true并且遇到无法正常化检查的字符串，则引发。

"doctype-not-allowed" [fatal]

如果配置参数“disallow-doctype”设置为true ，并true一个doctype，则引发。

"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-denormalisation”设置为false并且遇到处理器无法确定归一化属性的字符，则引发。

"unsupported-encoding" [fatal]

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

"unsupported-media-type" [fatal]

如果配置参数“supported-media-types-only-only”设置为true并且遇到不支持的介质类型，则引发。

除了提出定义的错误和警告之外，预计实施将会针对任何其他错误和警告情况（如IO错误（未找到文件，拒绝许可，...），XML格式良好错误，等等。

另见Document Object Model (DOM) Level 3 Load and Save Specification 。

Field Summary

Fields

Modifier and Type	Field and Description
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	Method and Description
void	abort() 中止加载当前由 LSParser加载的 LSParser 。
boolean	getAsync() true如果 LSParser是异步的， false如果是同步的。
boolean	getBusy() true如果 LSParser当前正在加载一个文件，否则 false 。
DOMConfiguration	getDomConfig() 解析输入源时使用的 DOMConfiguration对象。
LSParserFilter	getFilter() 当提供过滤器时，在构建DOM树结构时，实现将调用过滤器。
Document	parse(LSInput input) 从一个标识的资源中解析XML文档 LSInput 。
Document	parseURI(String uri) 从由URI引用[ IETF RFC 2396 ]标识的位置解析XML文档。
Node	parseWithContext(LSInput input, Node contextArg, short action) 从由所标识的资源中解析XML片段 LSInput和在与所指定的位置插入内容到现有文件 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声明或Text声明中指定的任何编码（另见第4.3节.3，“实体中的字符编码”，[ XML 1.0 ]）。 在LSInput中显式设置编码会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 ，请参阅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 ，请参阅DOMConfiguration的定义。 与[ DOM Level 3 Core ]不同，即使该参数设置为false ，内部子集的处理也始终false 。

"validate-if-schema"

有关此参数的DOMConfiguration ，请参阅DOMConfiguration的定义。 与[ DOM Level 3 Core ]不同，即使将此参数设置为false ，也始终会执行内部子集的false 。

"well-formed"

有关此参数的DOMConfiguration ，请参阅DOMConfiguration的定义。 与[ DOM Level 3 Core ]不同，此参数不能设置为false 。

getFilter

LSParserFilter getFilter()

当提供过滤器时，在构建DOM树结构时，实现将调用过滤器。 过滤器可以选择从正在构造的文档中删除元素，或者提前终止解析。
在DOMConfiguration参数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中定义了ACTION_TYPES组可能的操作。

结果

返回作为解析操作结果的节点。 如果结果是多个顶级节点，则返回第一个节点。

异常

DOMException - HIERARCHY_REQUEST_ERR：如果内容无法替代，则在上下文节点之前，之后或之后插入（在[ DOM Level 3 Core ]中也可以看到Node.insertBefore或Node.replaceChild ））。
NOT_SUPPORTED_ERR：如果LSParser不支持此方法，或者如果上下文节点的类型为Document ，并且DOM实现不支持替换DocumentType子Element或Element子节点，则DocumentType 。
NO_MODIFICATION_ALLOWED_ERR：如果上下文节点是只读节点并且内容正在追加到其子列表，或者上下文节点的父节点是只读节点，并且内容正在其子节点列表中，则引发。
INVALID_STATE_ERR：如果LSParser.busy属性为true则true 。

LSException - PARSE_ERR：如果LSParser无法加载XML片段，则引发。 如果DOM应用程序希望获得有关错误的详细信息， DOMErrorHandler使用参数“ error-handler ”附加一个DOMErrorHandler 。

abort

void abort()

中止当前由LSParser加载的文档的加载。 如果LSParser当前不忙，则调用此方法什么也不做。