-
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"
-
"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 theLSParser
. If theLSParser
is currently not busy, a call to this method does nothing.
-
-