-
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
信号。 此规范不会尝试准确定义何时应分派进度事件。 故意将其视为依赖于实现的。 以下是应用程序如何分派进度事件的一个示例:解析器开始接收数据后,将调度progress事件以指示解析开始。 从那里开始,为每个接收和处理的4096个字节的数据调度progress事件。 这只是一个例子,实现可以选择在解析时随时调度进度事件,或者根本不调度它们。 另请参见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”设置为
true
并且遇到不支持的介质类型,则true
。
除了提出已定义的错误和警告之外,预计实现还会针对任何其他错误和警告情况(例如IO错误(未找到文件,权限被拒绝,......),XML格式错误,提出特定于实现的错误和警告)等等。
另见Document Object Model (DOM) Level 3 Load and Save Specification 。
- 从以下版本开始:
- 1.5
-
-
字段汇总
字段 变量和类型 字段 描述 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
当前正在加载的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
。- 另请参见:
- 常数字段值
-
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
特定于解析操作。 此DOMConfiguration
对象中的任何参数值都不会自动传递到解析操作创建或使用的DOMConfiguration
上的Document
对象。 DOM应用程序负责将此DOMConfiguration
对象中的任何所需参数值传递给DOMConfiguration
对象引用的Document
对象。
除了[ DOM Level 3 Core ]中定义的DOMConfiguration接口中识别的参数外, 5157286513100的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:如果内容无法替换,则在上下文节点之前,之后或作为子节点Node.insertBefore
Node.replaceChild
(参见[ DOM Level 3 Core ]中的Node.insertBefore
或Node.replaceChild
)。
NOT_SUPPORTED_ERR:如果LSParser
不支持此方法,或者上下文节点的类型为Document
且DOM实现不支持替换DocumentType
子级或Element
子级,则DocumentType
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.
-
-