org.w3c.dom.ls
接口 LSParser

public interface LSParser

可以构建的对象接口，或者参数、来自各种输入源的 DOM 树。

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

如 [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 对象所支持的事件包括：

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 并且遇到了 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-denormalizations" 设置为 false 并且遇到了处理器无法为其确定标准化属性的字符，则引发此错误。

"unsupported-encoding" [fatal]

如果遇到了不支持的编码，则引发此错误。

"unsupported-media-type" [fatal]

如果配置参数 "supported-media-types-only" 设置为 true 并且遇到了不支持的媒体类型，则引发此错误。

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

另请参见《Document Object Model (DOM) Level 3 Load and Save Specification》。

字段摘要

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

方法摘要

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 引用 [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 特定于解析操作。在由解析操作创建或使用的 Document 上，没有参数值从此 DOMConfiguration 对象被自动传递到 DOMConfiguration 对象。DOM 应用程序负责将任何所需的参数值从此 DOMConfiguration 对象传递到由 Document 对象引用的 DOMConfiguration 对象。
除在 "DOMConfiguration" 接口（在 [DOM Level 3 Core] 中定义）上识别的参数之外，针对 LSParser 的 DOMConfiguration 对象还可以添加或修改以下参数：

"charset-overrides-xml-encoding"

true

[可选]（默认）如果高层协议（如 HTTP）[IETF RFC 2616] 提供了对正被处理的输入流的字符编码的指示，则将重写在 XML 声明或 Text 声明中指定的任何编码（另请参见 [XML 1.0] 中的 4.3.3 节 "Character Encoding in Entities"）。显式在 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 的节点，则为节点本身）用来解析默认属性和实体引用。
因为新的数据插入到文档，所以通过上下文节点的直接子节点或兄弟节点将触发至少一个 mutation 事件。
如果上下文节点是 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:如果内容不能替换、插入到上下文节点的前面、后面或作为它的子节点（另请参见 [DOM Level 3 Core] 中的 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 应用程序想获得关于错误的详细信息，则它必须附加一个使用参数 "error-handler" 的 DOMErrorHandler。

abort

void abort()

中断对当前由 LSParser 加载的文档的加载。如果当前 LSParser 不忙，则调用此方法无效。