所有类
org.w3c.dom.ls
| |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | ||||||||
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""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，则在调用过滤器前进行验证。