所有类


org.w3c.dom.ls
接口 LSParser


public interface LSParser

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

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

如 [DOM Level 3 Core] 中指定的那样,当通过 LSParser 第一次使文档可供使用时:

  • 从不会有两个 NODE_TEXT 类型的相邻节点,并且从不会有空的文本节点。
  • 期望 Attr 节点的 valuenodeValue 属性最初返回《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 片断,并将其内容插入到用 contextaction 参数指定的位置的现有文档。
 void setFilter(LSParserFilter filter)
          当提供过滤器时,实现将在构建 DOM 树结构时调出该过滤器。
 

字段详细信息

ACTION_APPEND_AS_CHILDREN

static final short ACTION_APPEND_AS_CHILDREN
将解析操作的结果追加为上下文节点的子节点。为了使此动作起作用,上下文节点必须是 ElementDocumentFragment

另请参见:
常量字段值

ACTION_REPLACE_CHILDREN

static final short ACTION_REPLACE_CHILDREN
用解析操作的结果替换上下文节点的所有子节点。为了使此动作有效,上下文节点必须是 ElementDocumentDocumentFragment

另请参见:
常量字段值

ACTION_INSERT_BEFORE

static final short ACTION_INSERT_BEFORE
把解析操作的结果作为上下文节点的直接前置兄弟节点插入。为了使此操作有效,上下文节点的父节点必须是 ElementDocumentFragment

另请参见:
常量字段值

ACTION_INSERT_AFTER

static final short ACTION_INSERT_AFTER
把解析操作的结果作为上下文节点的直接后续兄弟节点插入。为了使此操作有效,上下文节点的父节点必须是 ElementDocumentFragment

另请参见:
常量字段值

ACTION_REPLACE

static final short ACTION_REPLACE
用解析操作的结果替换上下文节点。为了使此操作有效,上下文节点必须具有父节点,并且父节点必须是 ElementDocumentFragment

另请参见:
常量字段值
方法详细信息

getDomConfig

DOMConfiguration getDomConfig()
解析输入源时使用的 DOMConfiguration 对象。此 DOMConfiguration 特定于解析操作。在由解析操作创建或使用的 Document 上,没有参数值从此 DOMConfiguration 对象被自动传递到 DOMConfiguration 对象。DOM 应用程序负责将任何所需的参数值从此 DOMConfiguration 对象传递到由 Document 对象引用的 DOMConfiguration 对象。
除在 "DOMConfiguration" 接口(在 [DOM Level 3 Core] 中定义)上识别的参数之外,针对 LSParserDOMConfiguration 对象还可以添加或修改以下参数:
"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,则在调用过滤器前进行验证。

微信小程序

微信扫一扫体验

微信公众账号

微信扫一扫加关注

发表
评论
返回
顶部